PKG-INFO 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430
  1. Metadata-Version: 2.1
  2. Name: python-crontab
  3. Version: 2.3.6
  4. Summary: Python Crontab API
  5. Home-page: https://gitlab.com/doctormo/python-crontab/
  6. Author: Martin Owens
  7. Author-email: doctormo@gmail.com
  8. License: LGPLv3
  9. Description: Python Crontab
  10. --------------
  11. .. image:: https://gitlab.com/doctormo/python-crontab/raw/master/branding.svg
  12. .. image:: https://badge.fury.io/py/python-crontab.svg
  13. :target: https://badge.fury.io/py/python-crontab
  14. .. image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
  15. :target: https://gitlab.com/doctormo/python-crontab/raw/master/COPYING
  16. Bug Reports and Development
  17. ===========================
  18. Please report any problems to the `GitLab issues tracker <https://gitlab.com/doctormo/python-crontab/issues>`_. Please use Git and push patches to the `GitLab project code hosting <https://gitlab.com/doctormo/python-crontab>`_.
  19. **Note:** If you get the error ``TypeError: __init__() takes exactly 2 arguments`` when using CronTab, you have the wrong module installed. You need to install ``python-crontab`` and not ``crontab`` from pypi or your local package manager and try again.
  20. Description
  21. ===========
  22. Crontab module for reading and writing crontab files and accessing the system cron
  23. automatically and simply using a direct API.
  24. Comparing the `below chart <http://en.wikipedia.org/wiki/Cron#CRON_expression>`_
  25. you will note that W, L, # and ? symbols are not supported as they are not
  26. standard Linux or SystemV crontab format.
  27. +-------------+-----------+-----------------+-------------------+-------------+
  28. |Field Name |Mandatory |Allowed Values |Special Characters |Extra Values |
  29. +=============+===========+=================+===================+=============+
  30. |Minutes |Yes |0-59 |\* / , - | < > |
  31. +-------------+-----------+-----------------+-------------------+-------------+
  32. |Hours |Yes |0-23 |\* / , - | < > |
  33. +-------------+-----------+-----------------+-------------------+-------------+
  34. |Day of month |Yes |1-31 |\* / , - | < > |
  35. +-------------+-----------+-----------------+-------------------+-------------+
  36. |Month |Yes |1-12 or JAN-DEC |\* / , - | < > |
  37. +-------------+-----------+-----------------+-------------------+-------------+
  38. |Day of week |Yes |0-6 or SUN-SAT |\* / , - | < > |
  39. +-------------+-----------+-----------------+-------------------+-------------+
  40. Extra Values are '<' for minimum value, such as 0 for minutes or 1 for months.
  41. And '>' for maximum value, such as 23 for hours or 12 for months.
  42. Supported special cases allow crontab lines to not use fields.
  43. These are the supported aliases which are not available in SystemV mode:
  44. =========== ============
  45. Case Meaning
  46. =========== ============
  47. @reboot Every boot
  48. @hourly 0 * * * *
  49. @daily 0 0 * * *
  50. @weekly 0 0 * * 0
  51. @monthly 0 0 1 * *
  52. @yearly 0 0 1 1 *
  53. @annually 0 0 1 1 *
  54. @midnight 0 0 * * *
  55. =========== ============
  56. How to Use the Module
  57. =====================
  58. **Note:** Several users have reported their new crontabs not saving automatically or that the module doesn't do anything. You **MUST** use write() if you want your edits to be saved out. See below for full details on the use of the write function.
  59. Getting access to a crontab can happen in five ways, three system methods that
  60. will work only on Unix and require you to have the right permissions::
  61. from crontab import CronTab
  62. empty_cron = CronTab()
  63. my_user_cron = CronTab(user=True)
  64. users_cron = CronTab(user='username')
  65. And two ways from non-system sources that will work on Windows too::
  66. file_cron = CronTab(tabfile='filename.tab')
  67. mem_cron = CronTab(tab="""
  68. * * * * * command
  69. """)
  70. Special per-command user flag for vixie cron format (new in 1.9)::
  71. system_cron = CronTab(tabfile='/etc/crontab', user=False)
  72. job = system_cron[0]
  73. job.user != None
  74. system_cron.new(command='new_command', user='root')
  75. Creating a new job is as simple as::
  76. job = cron.new(command='/usr/bin/echo')
  77. And setting the job's time restrictions::
  78. job.minute.during(5,50).every(5)
  79. job.hour.every(4)
  80. job.day.on(4, 5, 6)
  81. job.dow.on('SUN')
  82. job.dow.on('SUN', 'FRI')
  83. job.month.during('APR', 'NOV')
  84. Each time restriction will clear the previous restriction::
  85. job.hour.every(10) # Set to * */10 * * *
  86. job.hour.on(2) # Set to * 2 * * *
  87. Appending restrictions is explicit::
  88. job.hour.every(10) # Set to * */10 * * *
  89. job.hour.also.on(2) # Set to * 2,*/10 * * *
  90. Setting all time slices at once::
  91. job.setall(2, 10, '2-4', '*/2', None)
  92. job.setall('2 10 * * *')
  93. Setting the slice to a python date object::
  94. job.setall(time(10, 2))
  95. job.setall(date(2000, 4, 2))
  96. job.setall(datetime(2000, 4, 2, 10, 2))
  97. Run a jobs command. Running the job here will not effect it's
  98. existing schedule with another crontab process::
  99. job_standard_output = job.run()
  100. Creating a job with a comment::
  101. job = cron.new(command='/foo/bar', comment='SomeID')
  102. Get the comment or command for a job::
  103. command = job.command
  104. comment = job.comment
  105. Modify the comment or command on a job::
  106. job.set_command("new_script.sh")
  107. job.set_comment("New ID or comment here")
  108. Disabled or Enable Job::
  109. job.enable()
  110. job.enable(False)
  111. False == job.is_enabled()
  112. Validity Check::
  113. True == job.is_valid()
  114. Use a special syntax::
  115. job.every_reboot()
  116. Find an existing job by command sub-match or regular expression::
  117. iter = cron.find_command('bar') # matches foobar1
  118. iter = cron.find_command(re.compile(r'b[ab]r$'))
  119. Find an existing job by comment exact match or regular expression::
  120. iter = cron.find_comment('ID or some text')
  121. iter = cron.find_comment(re.compile(' or \w'))
  122. Find an existing job by schedule::
  123. iter = cron.find_time(2, 10, '2-4', '*/2', None)
  124. iter = cron.find_time("*/2 * * * *")
  125. Clean a job of all rules::
  126. job.clear()
  127. Iterate through all jobs, this includes disabled (commented out) cron jobs::
  128. for job in cron:
  129. print job
  130. Iterate through all lines, this includes all comments and empty lines::
  131. for line in cron.lines:
  132. print line
  133. Remove Items::
  134. cron.remove( job )
  135. cron.remove_all('echo')
  136. cron.remove_all(comment='foo')
  137. cron.remove_all(time='*/2')
  138. Clear entire cron of all jobs::
  139. cron.remove_all()
  140. Write CronTab back to system or filename::
  141. cron.write()
  142. Write CronTab to new filename::
  143. cron.write( 'output.tab' )
  144. Write to this user's crontab (unix only)::
  145. cron.write_to_user( user=True )
  146. Write to some other user's crontab::
  147. cron.write_to_user( user='bob' )
  148. Validate a cron time string::
  149. from crontab import CronSlices
  150. bool = CronSlices.is_valid('0/2 * * * *')
  151. Environment Variables
  152. =====================
  153. Some versions of vixie cron support variables outside of the command line.
  154. Sometimes just update the envronment when commands are run, the Cronie fork
  155. of vixie cron also supports CRON_TZ which looks like a regular variable but
  156. actually changes the times the jobs are run at.
  157. Very old vixie crons don't support per-job variables, but most do.
  158. Iterate through cron level environment variables::
  159. for (name, value) in cron.env.items():
  160. print name
  161. print value
  162. Create new or update cron level environment variables::
  163. print cron.env['SHELL']
  164. cron.env['SHELL'] = '/bin/bash'
  165. print cron.env
  166. Each job can also have a list of environment variables::
  167. for job in cron:
  168. job.env['NEW_VAR'] = 'A'
  169. print job.env
  170. Proceeding Unit Confusion
  171. =========================
  172. It is sometimes logical to think that job.hour.every(2) will set all proceeding
  173. units to '0' and thus result in "0 \*/2 * * \*". Instead you are controlling
  174. only the hours units and the minute column is unaffected. The real result would
  175. be "\* \*/2 * * \*" and maybe unexpected to those unfamiliar with crontabs.
  176. There is a special 'every' method on a job to clear the job's existing schedule
  177. and replace it with a simple single unit::
  178. job.every(4).hours() == '0 */4 * * *'
  179. job.every().dom() == '0 0 * * *'
  180. job.every().month() == '0 0 0 * *'
  181. job.every(2).dows() == '0 0 * * */2'
  182. This is a convenience method only, it does normal things with the existing api.
  183. Running the Scheduler
  184. =====================
  185. The module is able to run a cron tab as a daemon as long as the optional
  186. croniter module is installed; each process will block and errors will
  187. be logged (new in 2.0).
  188. (note this functionality is new and not perfect, if you find bugs report them!)
  189. Running the scheduler::
  190. tab = CronTab(tabfile='MyScripts.tab')
  191. for result in tab.run_scheduler():
  192. print "This was printed to stdout by the process."
  193. Do not do this, it won't work because it returns generator function::
  194. tab.run_scheduler()
  195. Timeout and cadence can be changed for testing or error management::
  196. for result in tab.run_scheduler(timeout=600):
  197. print "Will run jobs every 1 minutes for ten minutes from now()"
  198. for result in tab.run_scheduler(cadence=1, warp=True):
  199. print "Will run jobs every 1 second, counting each second as 1 minute"
  200. Frequency Calculation
  201. =====================
  202. Every job's schedule has a frequency. We can attempt to calculate the number
  203. of times a job would execute in a give amount of time. We have three simple
  204. methods::
  205. job.setall("1,2 1,2 * * *")
  206. job.frequency_per_day() == 4
  207. The per year frequency method will tell you how many days a year the
  208. job would execute::
  209. job.setall("* * 1,2 1,2 *")
  210. job.frequency_per_year(year=2010) == 4
  211. These are combined to give the number of times a job will execute in any year::
  212. job.setall("1,2 1,2 1,2 1,2 *")
  213. job.frequency(year=2010) == 16
  214. Frequency can be quickly checked using python built-in operators::
  215. job < "*/2 * * * *"
  216. job > job2
  217. job.slices == "*/5"
  218. Log Functionality
  219. =================
  220. The log functionality will read a cron log backwards to find you the last run
  221. instances of your crontab and cron jobs.
  222. The crontab will limit the returned entries to the user the crontab is for::
  223. cron = CronTab(user='root')
  224. for d in cron.log:
  225. print d['pid'] + " - " + d['date']
  226. Each job can return a log iterator too, these are filtered so you can see when
  227. the last execution was::
  228. for d in cron.find_command('echo')[0].log:
  229. print d['pid'] + " - " + d['date']
  230. All System CronTabs Functionality
  231. =================================
  232. The crontabs (note the plural) module can attempt to find all crontabs on the
  233. system. This works well for Linux systems with known locations for cron files
  234. and user spolls. It will even extract anacron jobs so you can get a picture
  235. of all the jobs running on your system::
  236. from crontabs import CronTabs
  237. for cron in CronTabs():
  238. print repr(cron)
  239. All jobs can be brought together to run various searches, all jobs are added
  240. to a CronTab object which can be used as documented above::
  241. jobs = CronTabs().all.find_command('foo')
  242. Schedule Functionality
  243. ======================
  244. If you have the croniter python module installed, you will have access to a
  245. schedule on each job. For example if you want to know when a job will next run::
  246. schedule = job.schedule(date_from=datetime.now())
  247. This creates a schedule croniter based on the job from the time specified. The
  248. default date_from is the current date/time if not specified. Next we can get
  249. the datetime of the next job::
  250. datetime = schedule.get_next()
  251. Or the previous::
  252. datetime = schedule.get_prev()
  253. The get methods work in the same way as the default croniter, except that they
  254. will return datetime objects by default instead of floats. If you want the
  255. original functionality, pass float into the method when calling::
  256. datetime = schedule.get_current(float)
  257. If you don't have the croniter module installed, you'll get an ImportError when
  258. you first try using the schedule function on your cron job object.
  259. Descriptor Functionality
  260. ========================
  261. If you have the cron-descriptor module installed, you will be able to ask for a
  262. translated string which describes the frequency of the job in the current
  263. locale language. This should be mostly human readable.
  264. print(job.description(use_24hour_time_format=True))
  265. See cron-descriptor for details of the supported languages and options.
  266. Extra Support
  267. =============
  268. - Support for vixie cron with username addition with user flag
  269. - Support for SunOS, AIX & HP with compatibility 'SystemV' mode.
  270. - Python 3.5.2 and Python 2.7 tested, python 2.6 removed from support.
  271. - Windows support works for non-system crontabs only.
  272. ( see mem_cron and file_cron examples above for usage )
  273. Platform: linux
  274. Classifier: Development Status :: 5 - Production/Stable
  275. Classifier: Development Status :: 6 - Mature
  276. Classifier: Intended Audience :: Developers
  277. Classifier: Intended Audience :: Information Technology
  278. Classifier: Intended Audience :: System Administrators
  279. Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
  280. Classifier: Operating System :: POSIX
  281. Classifier: Operating System :: POSIX :: Linux
  282. Classifier: Operating System :: POSIX :: SunOS/Solaris
  283. Classifier: Programming Language :: Python
  284. Classifier: Programming Language :: Python :: 2.7
  285. Classifier: Programming Language :: Python :: 3.5
  286. Provides: crontab
  287. Provides: crontabs
  288. Provides: cronlog
  289. Provides-Extra: cron-description
  290. Provides-Extra: cron-schedule