pax_global_header00006660000000000000000000000064146505046410014517gustar00rootroot0000000000000052 comment=27efe48d70e721fcf112fa8b899dec1b3a6cf2ca tempora-5.7.0/000077500000000000000000000000001465050464100131775ustar00rootroot00000000000000tempora-5.7.0/.coveragerc000066400000000000000000000003101465050464100153120ustar00rootroot00000000000000[run] omit = # leading `*/` for pytest-dev/pytest-cov#456 */.tox/* disable_warnings = couldnt-parse [report] show_missing = True exclude_also = # jaraco/skeleton#97 @overload if TYPE_CHECKING: tempora-5.7.0/.editorconfig000066400000000000000000000003661465050464100156610ustar00rootroot00000000000000root = true [*] charset = utf-8 indent_style = tab indent_size = 4 insert_final_newline = true end_of_line = lf [*.py] indent_style = space max_line_length = 88 [*.{yml,yaml}] indent_style = space indent_size = 2 [*.rst] indent_style = space tempora-5.7.0/.github/000077500000000000000000000000001465050464100145375ustar00rootroot00000000000000tempora-5.7.0/.github/FUNDING.yml000066400000000000000000000000271465050464100163530ustar00rootroot00000000000000tidelift: pypi/tempora tempora-5.7.0/.github/dependabot.yml000066400000000000000000000002241465050464100173650ustar00rootroot00000000000000version: 2 updates: - package-ecosystem: "pip" directory: "/" schedule: interval: "daily" allow: - dependency-type: "all" tempora-5.7.0/.github/workflows/000077500000000000000000000000001465050464100165745ustar00rootroot00000000000000tempora-5.7.0/.github/workflows/main.yml000066400000000000000000000055461465050464100202550ustar00rootroot00000000000000name: tests on: merge_group: push: branches-ignore: # temporary GH branches relating to merge queues (jaraco/skeleton#93) - gh-readonly-queue/** tags: # required if branches-ignore is supplied (jaraco/skeleton#103) - '**' pull_request: permissions: contents: read env: # Environment variable to support color support (jaraco/skeleton#66) FORCE_COLOR: 1 # Suppress noisy pip warnings PIP_DISABLE_PIP_VERSION_CHECK: 'true' PIP_NO_PYTHON_VERSION_WARNING: 'true' PIP_NO_WARN_SCRIPT_LOCATION: 'true' # Ensure tests can sense settings about the environment TOX_OVERRIDE: >- testenv.pass_env+=GITHUB_*,FORCE_COLOR jobs: test: strategy: # https://blog.jaraco.com/efficient-use-of-ci-resources/ matrix: python: - "3.8" - "3.12" platform: - ubuntu-latest - macos-latest - windows-latest include: - python: "3.9" platform: ubuntu-latest - python: "3.10" platform: ubuntu-latest - python: "3.11" platform: ubuntu-latest - python: pypy3.10 platform: ubuntu-latest runs-on: ${{ matrix.platform }} continue-on-error: ${{ matrix.python == '3.13' }} steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v4 with: python-version: ${{ matrix.python }} allow-prereleases: true - name: Install tox run: python -m pip install tox - name: Run run: tox collateral: strategy: fail-fast: false matrix: job: - diffcov - docs runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-python@v4 with: python-version: 3.x - name: Install tox run: python -m pip install tox - name: Eval ${{ matrix.job }} run: tox -e ${{ matrix.job }} check: # This job does nothing and is only used for the branch protection if: always() needs: - test - collateral runs-on: ubuntu-latest steps: - name: Decide whether the needed jobs succeeded or failed uses: re-actors/alls-green@release/v1 with: jobs: ${{ toJSON(needs) }} release: permissions: contents: write needs: - check if: github.event_name == 'push' && contains(github.ref, 'refs/tags/') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v4 with: python-version: 3.x - name: Install tox run: python -m pip install tox - name: Run run: tox -e release env: TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} tempora-5.7.0/.pre-commit-config.yaml000066400000000000000000000001641465050464100174610ustar00rootroot00000000000000repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.1.8 hooks: - id: ruff - id: ruff-format tempora-5.7.0/.readthedocs.yaml000066400000000000000000000005161465050464100164300ustar00rootroot00000000000000version: 2 python: install: - path: . extra_requirements: - doc # required boilerplate readthedocs/readthedocs.org#10401 build: os: ubuntu-lts-latest tools: python: latest # post-checkout job to ensure the clone isn't shallow jaraco/skeleton#114 jobs: post_checkout: - git fetch --unshallow || true tempora-5.7.0/LICENSE000066400000000000000000000017771465050464100142200ustar00rootroot00000000000000Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. tempora-5.7.0/NEWS.rst000066400000000000000000000101761465050464100145120ustar00rootroot00000000000000v5.7.0 ====== Features -------- - Add a tzinfos mapping and parse method for easy datetime parsing with timezone support. v5.6.0 ====== Features -------- - Removed dependency on pytz. (#29) - In utc.now(), bind late to allow for monkeypatching. (#31) v5.5.1 ====== Bugfixes -------- - Remove test dependency on backports.unittest_mock. (#26) v5.5.0 ====== Features -------- - Stopwatch now uses ``time.monotonic``. v5.4.0 ====== Features -------- - Require Python 3.8 or later. v5.3.0 ====== #24: Removed use of ``datetime.utc**`` functions deprecated in Python 3.12. v5.2.2 ====== #22: Fixed bug in tests that would fail when a leap year was about a year away. v5.2.1 ====== #21: Restored dependency on ``jaraco.functools``, still used in timing module. v5.2.0 ====== Remove dependency on jaraco.functools. v5.1.1 ====== Packaging refresh. v5.1.0 ====== Introduced ``infer_datetime`` and added some type hints. v5.0.2 ====== - Refreshed project. - Enrolled with Tidelift. v5.0.1 ====== - Refreshed project. v5.0.0 ====== - Removed deprecated ``divide_*`` functions and ``Parser`` class. - Require Python 3.7 or later. - #19: Fixed error reporting in parse_timedelta. v4.1.2 ====== - #18: Docs now build without warnings. v4.1.1 ====== - Fixed issue where digits were picked up in the unit when adjacent to the last unit. v4.1.0 ====== - Added support for more formats in ``parse_timedelta``. - #17: ``parse_timedelta`` now supports formats emitted by ``timeit``, including honoring nanoseconds at the microsecond resolution. v4.0.2 ====== - Refreshed package metadata. v4.0.1 ====== - Refreshed package metadata. v4.0.0 ====== - Removed ``strptime`` function in favor of `datetime.datetime.strptime `_. If passing a ``tzinfo`` parameter, instead invoke `.replace(tzinfo=...)` on the result. - Deprecated ``divide_timedelta`` and ``divide_timedelta_float`` now that Python supports this functionality natively. - Deprecated ``Parser`` class. The `dateutil.parser `_ provides more sophistication. v3.0.0 ====== - #10: ``strftime`` now reverts to the stdlib behavior for ``%u``. Use tempora 2.1 or later and the ``%µ`` for microseconds. v2.1.1 ====== - #8: Fixed error in ``PeriodicCommandFixedDelay.daily_at`` when timezone is more than 12 hours from UTC. v2.1.0 ====== - #9: Fixed error when date object is passed to ``strftime``. - #11: ``strftime`` now honors upstream expectation of rendering date values on time objects and vice versa. - #10: ``strftime`` now honors ``%µ`` for rendering just the "microseconds" as ``%u`` supported previously. In a future, backward-incompatible release, the ``%u`` behavior will revert to the behavior as found in stdlib. v2.0.0 ====== * Require Python 3.6 or later. * Removed DatetimeConstructor. 1.14.1 ====== #7: Fix failing doctest in ``parse_timedelta``. 1.14 ==== Package refresh, including use of declarative config in the package metadata. 1.13 ==== Enhancements to BackoffDelay: - Added ``.reset`` method. - Made iterable to retrieve delay values. 1.12 ==== Added UTC module (Python 3 only), inspired by the `utc project `_. 1.11 ==== #5: Scheduler now honors daylight savings times in the PeriodicCommands. 1.10 ==== Added ``timing.BackoffDelay``, suitable for implementing exponential backoff delays, such as those between retries. 1.9 === Added support for months, years to ``parse_timedelta``. 1.8 === Introducing ``timing.Timer``, featuring a ``expired`` method for detecting when a certain duration has been exceeded. 1.7.1 ===== #3: Stopwatch now behaves reliably during timezone changes and (presumably) daylight savings time changes. 1.7 === Update project skeleton. 1.6 === Adopt ``irc.schedule`` as ``tempora.schedule``. 1.5 === Adopt ``jaraco.timing`` as ``tempora.timing``. Automatic deployment with Travis-CI. 1.4 === Moved to Github. Improved test support on Python 2. 1.3 === Added divide_timedelta from ``svg.charts``. Added date_range from ``svg.charts``. tempora-5.7.0/README.rst000066400000000000000000000032031465050464100146640ustar00rootroot00000000000000.. image:: https://img.shields.io/pypi/v/tempora.svg :target: https://pypi.org/project/tempora .. image:: https://img.shields.io/pypi/pyversions/tempora.svg .. image:: https://github.com/jaraco/tempora/actions/workflows/main.yml/badge.svg :target: https://github.com/jaraco/tempora/actions?query=workflow%3A%22tests%22 :alt: tests .. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json :target: https://github.com/astral-sh/ruff :alt: Ruff .. image:: https://readthedocs.org/projects/tempora/badge/?version=latest :target: https://tempora.readthedocs.io/en/latest/?badge=latest .. image:: https://img.shields.io/badge/skeleton-2024-informational :target: https://blog.jaraco.com/skeleton .. image:: https://tidelift.com/badges/package/pypi/tempora :target: https://tidelift.com/subscription/pkg/pypi-tempora?utm_source=pypi-tempora&utm_medium=readme Objects and routines pertaining to date and time (tempora). Modules include: - tempora (top level package module) contains miscellaneous utilities and constants. - timing contains routines for measuring and profiling. - schedule contains an event scheduler. - utc contains routines for getting datetime-aware UTC values. For Enterprise ============== Available as part of the Tidelift Subscription. This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use. `Learn more `_. tempora-5.7.0/SECURITY.md000066400000000000000000000002641465050464100147720ustar00rootroot00000000000000# Security Contact To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure. tempora-5.7.0/conftest.py000066400000000000000000000006551465050464100154040ustar00rootroot00000000000000import sys import operator def pytest_collection_modifyitems(session, config, items): remove_parse_timedelta(items) def remove_parse_timedelta(items): # pragma: nocover """ Repr on older Pythons is different, so remove the offending test. """ if sys.version_info > (3, 7): return names = list(map(operator.attrgetter('name'), items)) del items[names.index('tempora.parse_timedelta')] tempora-5.7.0/docs/000077500000000000000000000000001465050464100141275ustar00rootroot00000000000000tempora-5.7.0/docs/conf.py000066400000000000000000000022051465050464100154250ustar00rootroot00000000000000extensions = [ 'sphinx.ext.autodoc', 'jaraco.packaging.sphinx', ] master_doc = "index" html_theme = "furo" # Link dates and other references in the changelog extensions += ['rst.linker'] link_files = { '../NEWS.rst': dict( using=dict(GH='https://github.com'), replace=[ dict( pattern=r'(Issue #|\B#)(?P\d+)', url='{package_url}/issues/{issue}', ), dict( pattern=r'(?m:^((?Pv?\d+(\.\d+){1,2}))\n[-=]+\n)', with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n', ), dict( pattern=r'PEP[- ](?P\d+)', url='https://peps.python.org/pep-{pep_number:0>4}/', ), ], ) } # Be strict about any broken references nitpicky = True # Include Python intersphinx mapping to prevent failures # jaraco/skeleton#51 extensions += ['sphinx.ext.intersphinx'] intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), } # Preserve authored syntax for defaults autodoc_preserve_defaults = True extensions += ['jaraco.tidelift'] tempora-5.7.0/docs/history.rst000066400000000000000000000001161465050464100163600ustar00rootroot00000000000000:tocdepth: 2 .. _changes: History ******* .. include:: ../NEWS (links).rst tempora-5.7.0/docs/index.rst000066400000000000000000000012361465050464100157720ustar00rootroot00000000000000Welcome to |project| documentation! =================================== .. sidebar-links:: :home: :pypi: .. toctree:: :maxdepth: 1 history .. tidelift-referral-banner:: .. automodule:: tempora :members: :undoc-members: :show-inheritance: Timing ------ .. automodule:: tempora.timing :members: :undoc-members: :show-inheritance: Schedule -------- .. automodule:: tempora.schedule :members: :undoc-members: :show-inheritance: UTC --- .. automodule:: tempora.utc :members: :undoc-members: :show-inheritance: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` tempora-5.7.0/mypy.ini000066400000000000000000000002321465050464100146730ustar00rootroot00000000000000[mypy] ignore_missing_imports = True # required to support namespace packages # https://github.com/python/mypy/issues/14057 explicit_package_bases = True tempora-5.7.0/pyproject.toml000066400000000000000000000025001465050464100161100ustar00rootroot00000000000000[build-system] requires = ["setuptools>=61.2", "setuptools_scm[toml]>=3.4.1"] build-backend = "setuptools.build_meta" [project] name = "tempora" authors = [ { name = "Jason R. Coombs", email = "jaraco@jaraco.com" }, ] description = "Objects and routines pertaining to date and time (tempora)" readme = "README.rst" classifiers = [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", ] requires-python = ">=3.8" dependencies = [ "jaraco.functools>=1.20", "python-dateutil", ] dynamic = ["version"] [project.urls] Source = "https://github.com/jaraco/tempora" [project.optional-dependencies] test = [ # upstream "pytest >= 6, != 8.1.*", "pytest-checkdocs >= 2.4", "pytest-cov", "pytest-mypy", "pytest-enabler >= 2.2", "pytest-ruff >= 0.2.1; sys_platform != 'cygwin'", # local "pytest-freezer", "backports.zoneinfo; python_version < '3.9'", "tzdata; platform_system == 'Windows'", "types-python-dateutil", ] doc = [ # upstream "sphinx >= 3.5", "jaraco.packaging >= 9.3", "rst.linker >= 1.9", "furo", "sphinx-lint", # tidelift "jaraco.tidelift >= 1.4", # local ] [project.scripts] calc-prorate = "tempora:calculate_prorated_values" [tool.setuptools_scm] tempora-5.7.0/pytest.ini000066400000000000000000000012431465050464100152300ustar00rootroot00000000000000[pytest] norecursedirs=dist build .tox .eggs addopts= --doctest-modules --import-mode importlib consider_namespace_packages=true filterwarnings= ## upstream # Ensure ResourceWarnings are emitted default::ResourceWarning # realpython/pytest-mypy#152 ignore:'encoding' argument not specified::pytest_mypy # python/cpython#100750 ignore:'encoding' argument not specified::platform # pypa/build#615 ignore:'encoding' argument not specified::build.env # dateutil/dateutil#1284 ignore:datetime.datetime.utcfromtimestamp:DeprecationWarning:dateutil.tz.tz ## end upstream # spulec/freezegun#508 ignore:datetime.datetime.utcnow:DeprecationWarning:freezegun.api tempora-5.7.0/ruff.toml000066400000000000000000000010201465050464100150270ustar00rootroot00000000000000[lint] extend-select = [ "C901", "PERF401", "W", ] ignore = [ # https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules "W191", "E111", "E114", "E117", "D206", "D300", "Q000", "Q001", "Q002", "Q003", "COM812", "COM819", "ISC001", "ISC002", ] [format] # Enable preview to get hugged parenthesis unwrapping and other nice surprises # See https://github.com/jaraco/skeleton/pull/133#issuecomment-2239538373 preview = true # https://docs.astral.sh/ruff/settings/#format_quote-style quote-style = "preserve" tempora-5.7.0/tempora/000077500000000000000000000000001465050464100146465ustar00rootroot00000000000000tempora-5.7.0/tempora/__init__.py000066400000000000000000000461761465050464100167750ustar00rootroot00000000000000"Objects and routines pertaining to date and time (tempora)" import datetime import time import re import numbers import functools import contextlib from numbers import Number from typing import Union, Tuple, Iterable from typing import cast import dateutil.parser import dateutil.tz # some useful constants osc_per_year = 290_091_329_207_984_000 """ mean vernal equinox year expressed in oscillations of atomic cesium at the year 2000 (see http://webexhibits.org/calendars/timeline.html for more info). """ osc_per_second = 9_192_631_770 seconds_per_second = 1 seconds_per_year = 31_556_940 seconds_per_minute = 60 minutes_per_hour = 60 hours_per_day = 24 seconds_per_hour = seconds_per_minute * minutes_per_hour seconds_per_day = seconds_per_hour * hours_per_day days_per_year = seconds_per_year / seconds_per_day thirty_days = datetime.timedelta(days=30) # these values provide useful averages six_months = datetime.timedelta(days=days_per_year / 2) seconds_per_month = seconds_per_year / 12 hours_per_month = hours_per_day * days_per_year / 12 @functools.lru_cache() def _needs_year_help() -> bool: """ Some versions of Python render %Y with only three characters :( https://bugs.python.org/issue39103 """ return len(datetime.date(900, 1, 1).strftime('%Y')) != 4 AnyDatetime = Union[datetime.datetime, datetime.date, datetime.time] StructDatetime = Union[Tuple[int, ...], time.struct_time] def ensure_datetime(ob: AnyDatetime) -> datetime.datetime: """ Given a datetime or date or time object from the ``datetime`` module, always return a datetime using default values. """ if isinstance(ob, datetime.datetime): return ob date = cast(datetime.date, ob) time = cast(datetime.time, ob) if isinstance(ob, datetime.date): time = datetime.time() if isinstance(ob, datetime.time): date = datetime.date(1900, 1, 1) return datetime.datetime.combine(date, time) def infer_datetime(ob: Union[AnyDatetime, StructDatetime]) -> datetime.datetime: if isinstance(ob, (time.struct_time, tuple)): ob = datetime.datetime(*ob[:6]) # type: ignore return ensure_datetime(ob) def strftime(fmt: str, t: Union[AnyDatetime, tuple, time.struct_time]) -> str: """ Portable strftime. In the stdlib, strftime has `known portability problems `_. This function aims to smooth over those issues and provide a consistent experience across the major platforms. >>> strftime('%Y', datetime.datetime(1890, 1, 1)) '1890' >>> strftime('%Y', datetime.datetime(900, 1, 1)) '0900' Supports time.struct_time, tuples, and datetime.datetime objects. >>> strftime('%Y-%m-%d', (1976, 5, 7)) '1976-05-07' Also supports date objects >>> strftime('%Y', datetime.date(1976, 5, 7)) '1976' Also supports milliseconds using %s. >>> strftime('%s', datetime.time(microsecond=20000)) '020' Also supports microseconds (3 digits) using %µ >>> strftime('%µ', datetime.time(microsecond=123456)) '456' Historically, %u was used for microseconds, but now it honors the value rendered by stdlib. >>> strftime('%u', datetime.date(1976, 5, 7)) '5' Also supports microseconds (6 digits) using %f >>> strftime('%f', datetime.time(microsecond=23456)) '023456' Even supports time values on date objects (discouraged): >>> strftime('%f', datetime.date(1976, 1, 1)) '000000' >>> strftime('%µ', datetime.date(1976, 1, 1)) '000' >>> strftime('%s', datetime.date(1976, 1, 1)) '000' And vice-versa: >>> strftime('%Y', datetime.time()) '1900' """ t = infer_datetime(t) subs = ( ('%s', '%03d' % (t.microsecond // 1000)), ('%µ', '%03d' % (t.microsecond % 1000)), ) + (('%Y', '%04d' % t.year),) * _needs_year_help() def doSub(s, sub): return s.replace(*sub) def doSubs(s): return functools.reduce(doSub, subs, s) fmt = '%%'.join(map(doSubs, fmt.split('%%'))) return t.strftime(fmt) def datetime_mod(dt, period, start=None): """ Find the time which is the specified date/time truncated to the time delta relative to the start date/time. By default, the start time is midnight of the same day as the specified date/time. >>> datetime_mod(datetime.datetime(2004, 1, 2, 3), ... datetime.timedelta(days = 1.5), ... start = datetime.datetime(2004, 1, 1)) datetime.datetime(2004, 1, 1, 0, 0) >>> datetime_mod(datetime.datetime(2004, 1, 2, 13), ... datetime.timedelta(days = 1.5), ... start = datetime.datetime(2004, 1, 1)) datetime.datetime(2004, 1, 2, 12, 0) >>> datetime_mod(datetime.datetime(2004, 1, 2, 13), ... datetime.timedelta(days = 7), ... start = datetime.datetime(2004, 1, 1)) datetime.datetime(2004, 1, 1, 0, 0) >>> datetime_mod(datetime.datetime(2004, 1, 10, 13), ... datetime.timedelta(days = 7), ... start = datetime.datetime(2004, 1, 1)) datetime.datetime(2004, 1, 8, 0, 0) """ if start is None: # use midnight of the same day start = datetime.datetime.combine(dt.date(), datetime.time()) # calculate the difference between the specified time and the start date. delta = dt - start # now aggregate the delta and the period into microseconds # Use microseconds because that's the highest precision of these time # pieces. Also, using microseconds ensures perfect precision (no floating # point errors). def get_time_delta_microseconds(td): return (td.days * seconds_per_day + td.seconds) * 1000000 + td.microseconds delta, period = map(get_time_delta_microseconds, (delta, period)) offset = datetime.timedelta(microseconds=delta % period) # the result is the original specified time minus the offset result = dt - offset return result def datetime_round(dt, period, start=None): """ Find the nearest even period for the specified date/time. >>> datetime_round(datetime.datetime(2004, 11, 13, 8, 11, 13), ... datetime.timedelta(hours = 1)) datetime.datetime(2004, 11, 13, 8, 0) >>> datetime_round(datetime.datetime(2004, 11, 13, 8, 31, 13), ... datetime.timedelta(hours = 1)) datetime.datetime(2004, 11, 13, 9, 0) >>> datetime_round(datetime.datetime(2004, 11, 13, 8, 30), ... datetime.timedelta(hours = 1)) datetime.datetime(2004, 11, 13, 9, 0) """ result = datetime_mod(dt, period, start) if abs(dt - result) >= period // 2: result += period return result def get_nearest_year_for_day(day): """ Returns the nearest year to now inferred from a Julian date. >>> freezer = getfixture('freezer') >>> freezer.move_to('2019-05-20') >>> get_nearest_year_for_day(20) 2019 >>> get_nearest_year_for_day(340) 2018 >>> freezer.move_to('2019-12-15') >>> get_nearest_year_for_day(20) 2020 """ now = time.gmtime() result = now.tm_year # if the day is far greater than today, it must be from last year if day - now.tm_yday > 365 // 2: result -= 1 # if the day is far less than today, it must be for next year. if now.tm_yday - day > 365 // 2: result += 1 return result def gregorian_date(year, julian_day): """ Gregorian Date is defined as a year and a julian day (1-based index into the days of the year). >>> gregorian_date(2007, 15) datetime.date(2007, 1, 15) """ result = datetime.date(year, 1, 1) result += datetime.timedelta(days=julian_day - 1) return result def get_period_seconds(period): """ return the number of seconds in the specified period >>> get_period_seconds('day') 86400 >>> get_period_seconds(86400) 86400 >>> get_period_seconds(datetime.timedelta(hours=24)) 86400 >>> get_period_seconds('day + os.system("rm -Rf *")') Traceback (most recent call last): ... ValueError: period not in (second, minute, hour, day, month, year) """ if isinstance(period, str): try: name = 'seconds_per_' + period.lower() result = globals()[name] except KeyError: msg = "period not in (second, minute, hour, day, month, year)" raise ValueError(msg) elif isinstance(period, numbers.Number): result = period elif isinstance(period, datetime.timedelta): result = period.days * get_period_seconds('day') + period.seconds else: raise TypeError('period must be a string or integer') return result def get_date_format_string(period): """ For a given period (e.g. 'month', 'day', or some numeric interval such as 3600 (in secs)), return the format string that can be used with strftime to format that time to specify the times across that interval, but no more detailed. For example, >>> get_date_format_string('month') '%Y-%m' >>> get_date_format_string(3600) '%Y-%m-%d %H' >>> get_date_format_string('hour') '%Y-%m-%d %H' >>> get_date_format_string(None) Traceback (most recent call last): ... TypeError: period must be a string or integer >>> get_date_format_string('garbage') Traceback (most recent call last): ... ValueError: period not in (second, minute, hour, day, month, year) """ # handle the special case of 'month' which doesn't have # a static interval in seconds if isinstance(period, str) and period.lower() == 'month': return '%Y-%m' file_period_secs = get_period_seconds(period) format_pieces = ('%Y', '-%m-%d', ' %H', '-%M', '-%S') seconds_per_second = 1 intervals = ( seconds_per_year, seconds_per_day, seconds_per_hour, seconds_per_minute, seconds_per_second, ) mods = list(map(lambda interval: file_period_secs % interval, intervals)) format_pieces = format_pieces[: mods.index(0) + 1] return ''.join(format_pieces) def calculate_prorated_values(): """ >>> monkeypatch = getfixture('monkeypatch') >>> import builtins >>> monkeypatch.setattr(builtins, 'input', lambda prompt: '3/hour') >>> calculate_prorated_values() per minute: 0.05 per hour: 3.0 per day: 72.0 per month: 2191.454166666667 per year: 26297.45 """ rate = input("Enter the rate (3/hour, 50/month)> ") for period, value in _prorated_values(rate): print(f"per {period}: {value}") def _prorated_values(rate: str) -> Iterable[Tuple[str, Number]]: """ Given a rate (a string in units per unit time), and return that same rate for various time periods. >>> for period, value in _prorated_values('20/hour'): ... print('{period}: {value:0.3f}'.format(**locals())) minute: 0.333 hour: 20.000 day: 480.000 month: 14609.694 year: 175316.333 """ match = re.match(r'(?P[\d.]+)/(?P\w+)$', rate) res = cast(re.Match, match).groupdict() value = float(res['value']) value_per_second = value / get_period_seconds(res['period']) for period in ('minute', 'hour', 'day', 'month', 'year'): period_value = value_per_second * get_period_seconds(period) yield period, period_value def parse_timedelta(str): """ Take a string representing a span of time and parse it to a time delta. Accepts any string of comma-separated numbers each with a unit indicator. >>> parse_timedelta('1 day') datetime.timedelta(days=1) >>> parse_timedelta('1 day, 30 seconds') datetime.timedelta(days=1, seconds=30) >>> parse_timedelta('47.32 days, 20 minutes, 15.4 milliseconds') datetime.timedelta(days=47, seconds=28848, microseconds=15400) Supports weeks, months, years >>> parse_timedelta('1 week') datetime.timedelta(days=7) >>> parse_timedelta('1 year, 1 month') datetime.timedelta(days=395, seconds=58685) Note that months and years strict intervals, not aligned to a calendar: >>> date = datetime.datetime.fromisoformat('2000-01-01') >>> later = date + parse_timedelta('1 year') >>> diff = later.replace(year=date.year) - date >>> diff.seconds 20940 >>> parse_timedelta('foo') Traceback (most recent call last): ... ValueError: Unexpected 'foo' >>> parse_timedelta('14 seconds foo') Traceback (most recent call last): ... ValueError: Unexpected 'foo' Supports abbreviations: >>> parse_timedelta('1s') datetime.timedelta(seconds=1) >>> parse_timedelta('1sec') datetime.timedelta(seconds=1) >>> parse_timedelta('5min1sec') datetime.timedelta(seconds=301) >>> parse_timedelta('1 ms') datetime.timedelta(microseconds=1000) >>> parse_timedelta('1 µs') datetime.timedelta(microseconds=1) >>> parse_timedelta('1 us') datetime.timedelta(microseconds=1) And supports the common colon-separated duration: >>> parse_timedelta('14:00:35.362') datetime.timedelta(seconds=50435, microseconds=362000) TODO: Should this be 14 hours or 14 minutes? >>> parse_timedelta('14:00') datetime.timedelta(seconds=50400) >>> parse_timedelta('14:00 minutes') Traceback (most recent call last): ... ValueError: Cannot specify units with composite delta Nanoseconds get rounded to the nearest microsecond: >>> parse_timedelta('600 ns') datetime.timedelta(microseconds=1) >>> parse_timedelta('.002 µs, 499 ns') datetime.timedelta(microseconds=1) Expect ValueError for other invalid inputs. >>> parse_timedelta('13 feet') Traceback (most recent call last): ... ValueError: Invalid unit feets """ return _parse_timedelta_nanos(str).resolve() def _parse_timedelta_nanos(str): parts = re.finditer(r'(?P[\d.:]+)\s?(?P[^\W\d_]+)?', str) chk_parts = _check_unmatched(parts, str) deltas = map(_parse_timedelta_part, chk_parts) return sum(deltas, _Saved_NS()) def _check_unmatched(matches, text): """ Ensure no words appear in unmatched text. """ def check_unmatched(unmatched): found = re.search(r'\w+', unmatched) if found: raise ValueError(f"Unexpected {found.group(0)!r}") pos = 0 for match in matches: check_unmatched(text[pos : match.start()]) yield match pos = match.end() check_unmatched(text[pos:]) _unit_lookup = { 'µs': 'microsecond', 'µsec': 'microsecond', 'us': 'microsecond', 'usec': 'microsecond', 'micros': 'microsecond', 'ms': 'millisecond', 'msec': 'millisecond', 'millis': 'millisecond', 's': 'second', 'sec': 'second', 'h': 'hour', 'hr': 'hour', 'm': 'minute', 'min': 'minute', 'w': 'week', 'wk': 'week', 'd': 'day', 'ns': 'nanosecond', 'nsec': 'nanosecond', 'nanos': 'nanosecond', } def _resolve_unit(raw_match): if raw_match is None: return 'second' text = raw_match.lower() return _unit_lookup.get(text, text) def _parse_timedelta_composite(raw_value, unit): if unit != 'seconds': raise ValueError("Cannot specify units with composite delta") values = raw_value.split(':') units = 'hours', 'minutes', 'seconds' composed = ' '.join(f'{value} {unit}' for value, unit in zip(values, units)) return _parse_timedelta_nanos(composed) def _parse_timedelta_part(match): unit = _resolve_unit(match.group('unit')) if not unit.endswith('s'): unit += 's' raw_value = match.group('value') if ':' in raw_value: return _parse_timedelta_composite(raw_value, unit) value = float(raw_value) if unit == 'months': unit = 'years' value = value / 12 if unit == 'years': unit = 'days' value = value * days_per_year return _Saved_NS.derive(unit, value) class _Saved_NS: """ Bundle a timedelta with nanoseconds. >>> _Saved_NS.derive('microseconds', .001) _Saved_NS(td=datetime.timedelta(0), nanoseconds=1) """ td = datetime.timedelta() nanoseconds = 0 multiplier = dict( seconds=1000000000, milliseconds=1000000, microseconds=1000, ) def __init__(self, **kwargs): vars(self).update(kwargs) @classmethod def derive(cls, unit, value): if unit == 'nanoseconds': return _Saved_NS(nanoseconds=value) try: raw_td = datetime.timedelta(**{unit: value}) except TypeError: raise ValueError(f"Invalid unit {unit}") res = _Saved_NS(td=raw_td) with contextlib.suppress(KeyError): res.nanoseconds = int(value * cls.multiplier[unit]) % 1000 return res def __add__(self, other): return _Saved_NS( td=self.td + other.td, nanoseconds=self.nanoseconds + other.nanoseconds ) def resolve(self): """ Resolve any nanoseconds into the microseconds field, discarding any nanosecond resolution (but honoring partial microseconds). """ addl_micros = round(self.nanoseconds / 1000) return self.td + datetime.timedelta(microseconds=addl_micros) def __repr__(self): return f'_Saved_NS(td={self.td!r}, nanoseconds={self.nanoseconds!r})' def date_range(start=None, stop=None, step=None): """ Much like the built-in function range, but works with dates >>> range_items = date_range( ... datetime.datetime(2005,12,21), ... datetime.datetime(2005,12,25), ... ) >>> my_range = tuple(range_items) >>> datetime.datetime(2005,12,21) in my_range True >>> datetime.datetime(2005,12,22) in my_range True >>> datetime.datetime(2005,12,25) in my_range False >>> from_now = date_range(stop=datetime.datetime(2099, 12, 31)) >>> next(from_now) datetime.datetime(...) """ if step is None: step = datetime.timedelta(days=1) if start is None: start = datetime.datetime.now() while start < stop: yield start start += step tzinfos = dict( AEST=dateutil.tz.gettz("Australia/Sydney"), AEDT=dateutil.tz.gettz("Australia/Sydney"), ACST=dateutil.tz.gettz("Australia/Darwin"), ACDT=dateutil.tz.gettz("Australia/Adelaide"), AWST=dateutil.tz.gettz("Australia/Perth"), EST=dateutil.tz.gettz("America/New_York"), EDT=dateutil.tz.gettz("America/New_York"), CST=dateutil.tz.gettz("America/Chicago"), CDT=dateutil.tz.gettz("America/Chicago"), MST=dateutil.tz.gettz("America/Denver"), MDT=dateutil.tz.gettz("America/Denver"), PST=dateutil.tz.gettz("America/Los_Angeles"), PDT=dateutil.tz.gettz("America/Los_Angeles"), GMT=dateutil.tz.gettz("Etc/GMT"), UTC=dateutil.tz.gettz("UTC"), CET=dateutil.tz.gettz("Europe/Berlin"), CEST=dateutil.tz.gettz("Europe/Berlin"), IST=dateutil.tz.gettz("Asia/Kolkata"), BST=dateutil.tz.gettz("Europe/London"), MSK=dateutil.tz.gettz("Europe/Moscow"), EET=dateutil.tz.gettz("Europe/Helsinki"), EEST=dateutil.tz.gettz("Europe/Helsinki"), # Add more mappings as needed ) def parse(*args, **kwargs): """ Parse the input using dateutil.parser.parse with friendly tz support. >>> parse('2024-07-26 12:59:00 EDT') datetime.datetime(...America/New_York...) """ return dateutil.parser.parse(*args, tzinfos=tzinfos, **kwargs) tempora-5.7.0/tempora/schedule.py000066400000000000000000000125431465050464100170210ustar00rootroot00000000000000""" Classes for calling functions a schedule. Has time zone support. For example, to run a job at 08:00 every morning in 'Asia/Calcutta': >>> from tests.compat.py38 import zoneinfo >>> job = lambda: print("time is now", datetime.datetime()) >>> time = datetime.time(8, tzinfo=zoneinfo.ZoneInfo('Asia/Calcutta')) >>> cmd = PeriodicCommandFixedDelay.daily_at(time, job) >>> sched = InvokeScheduler() >>> sched.add(cmd) >>> while True: # doctest: +SKIP ... sched.run_pending() ... time.sleep(.1) By default, the scheduler uses timezone-aware times in UTC. A client may override the default behavior by overriding ``now`` and ``from_timestamp`` functions. >>> now() datetime.datetime(...utc) >>> from_timestamp(1718723533.7685602) datetime.datetime(...utc) """ import datetime import numbers import abc import bisect from .utc import now, fromtimestamp as from_timestamp class DelayedCommand(datetime.datetime): """ A command to be executed after some delay (seconds or timedelta). """ @classmethod def from_datetime(cls, other): return cls( other.year, other.month, other.day, other.hour, other.minute, other.second, other.microsecond, other.tzinfo, ) @classmethod def after(cls, delay, target): if not isinstance(delay, datetime.timedelta): delay = datetime.timedelta(seconds=delay) due_time = now() + delay cmd = cls.from_datetime(due_time) cmd.delay = delay cmd.target = target return cmd @staticmethod def _from_timestamp(input): """ If input is a real number, interpret it as a Unix timestamp (seconds sinc Epoch in UTC) and return a timezone-aware datetime object. Otherwise return input unchanged. """ if not isinstance(input, numbers.Real): return input return from_timestamp(input) @classmethod def at_time(cls, at, target): """ Construct a DelayedCommand to come due at `at`, where `at` may be a datetime or timestamp. """ at = cls._from_timestamp(at) cmd = cls.from_datetime(at) cmd.delay = at - now() cmd.target = target return cmd def due(self): return now() >= self class PeriodicCommand(DelayedCommand): """ Like a delayed command, but expect this command to run every delay seconds. """ def _next_time(self): """ Add delay to self, localized """ return self + self.delay def next(self): cmd = self.__class__.from_datetime(self._next_time()) cmd.delay = self.delay cmd.target = self.target return cmd def __setattr__(self, key, value): if key == 'delay' and not value > datetime.timedelta(): raise ValueError("A PeriodicCommand must have a positive, non-zero delay.") super().__setattr__(key, value) class PeriodicCommandFixedDelay(PeriodicCommand): """ Like a periodic command, but don't calculate the delay based on the current time. Instead use a fixed delay following the initial run. """ @classmethod def at_time(cls, at, delay, target): """ >>> cmd = PeriodicCommandFixedDelay.at_time(0, 30, None) >>> cmd.delay.total_seconds() 30.0 """ at = cls._from_timestamp(at) cmd = cls.from_datetime(at) if isinstance(delay, numbers.Number): delay = datetime.timedelta(seconds=delay) cmd.delay = delay cmd.target = target return cmd @classmethod def daily_at(cls, at, target): """ Schedule a command to run at a specific time each day. >>> from tempora import utc >>> noon = utc.time(12, 0) >>> cmd = PeriodicCommandFixedDelay.daily_at(noon, None) >>> cmd.delay.total_seconds() 86400.0 """ daily = datetime.timedelta(days=1) # convert when to the next datetime matching this time when = datetime.datetime.combine(datetime.date.today(), at) when -= daily while when < now(): when += daily return cls.at_time(when, daily, target) class Scheduler: """ A rudimentary abstract scheduler accepting DelayedCommands and dispatching them on schedule. """ def __init__(self): self.queue = [] def add(self, command): assert isinstance(command, DelayedCommand) bisect.insort(self.queue, command) def run_pending(self): while self.queue: command = self.queue[0] if not command.due(): break self.run(command) if isinstance(command, PeriodicCommand): self.add(command.next()) del self.queue[0] @abc.abstractmethod def run(self, command): """ Run the command """ class InvokeScheduler(Scheduler): """ Command targets are functions to be invoked on schedule. """ def run(self, command): command.target() class CallbackScheduler(Scheduler): """ Command targets are passed to a dispatch callable on schedule. """ def __init__(self, dispatch): super().__init__() self.dispatch = dispatch def run(self, command): self.dispatch(command.target) tempora-5.7.0/tempora/timing.py000066400000000000000000000136651465050464100165220ustar00rootroot00000000000000import collections.abc import contextlib import datetime import functools import numbers import time import jaraco.functools class Stopwatch: """ A simple stopwatch that starts automatically. >>> w = Stopwatch() >>> _1_sec = datetime.timedelta(seconds=1) >>> w.split() < _1_sec True >>> time.sleep(1.0) >>> w.split() >= _1_sec True >>> w.stop() >= _1_sec True >>> w.reset() >>> w.start() >>> w.split() < _1_sec True Launch the Stopwatch in a context: >>> with Stopwatch() as watch: ... assert isinstance(watch.split(), datetime.timedelta) After exiting the context, the watch is stopped; read the elapsed time directly: >>> watch.elapsed datetime.timedelta(...) >>> watch.elapsed.seconds 0 """ def __init__(self): self.reset() self.start() def reset(self): self.elapsed = datetime.timedelta(0) with contextlib.suppress(AttributeError): del self._start def _diff(self): return datetime.timedelta(seconds=time.monotonic() - self._start) def start(self): self._start = time.monotonic() def stop(self): self.elapsed += self._diff() del self._start return self.elapsed def split(self): return self.elapsed + self._diff() # context manager support def __enter__(self): self.start() return self def __exit__(self, exc_type, exc_value, traceback): self.stop() class IntervalGovernor: """ Decorate a function to only allow it to be called once per min_interval. Otherwise, it returns None. >>> gov = IntervalGovernor(30) >>> gov.min_interval.total_seconds() 30.0 """ def __init__(self, min_interval): if isinstance(min_interval, numbers.Number): min_interval = datetime.timedelta(seconds=min_interval) self.min_interval = min_interval self.last_call = None def decorate(self, func): @functools.wraps(func) def wrapper(*args, **kwargs): allow = not self.last_call or self.last_call.split() > self.min_interval if allow: self.last_call = Stopwatch() return func(*args, **kwargs) return wrapper __call__ = decorate class Timer(Stopwatch): """ Watch for a target elapsed time. >>> t = Timer(0.1) >>> t.expired() False >>> __import__('time').sleep(0.15) >>> t.expired() True """ def __init__(self, target=float('Inf')): self.target = self._accept(target) super().__init__() @staticmethod def _accept(target): """ Accept None or ∞ or datetime or numeric for target >>> Timer._accept(datetime.timedelta(seconds=30)) 30.0 >>> Timer._accept(None) inf """ if isinstance(target, datetime.timedelta): target = target.total_seconds() if target is None: # treat None as infinite target target = float('Inf') return target def expired(self): return self.split().total_seconds() > self.target class BackoffDelay(collections.abc.Iterator): """ Exponential backoff delay. Useful for defining delays between retries. Consider for use with ``jaraco.functools.retry_call`` as the cleanup. Default behavior has no effect; a delay or jitter must be supplied for the call to be non-degenerate. >>> bd = BackoffDelay() >>> bd() >>> bd() The following instance will delay 10ms for the first call, 20ms for the second, etc. >>> bd = BackoffDelay(delay=0.01, factor=2) >>> bd() >>> bd() Inspect and adjust the state of the delay anytime. >>> bd.delay 0.04 >>> bd.delay = 0.01 Set limit to prevent the delay from exceeding bounds. >>> bd = BackoffDelay(delay=0.01, factor=2, limit=0.015) >>> bd() >>> bd.delay 0.015 To reset the backoff, simply call ``.reset()``: >>> bd.reset() >>> bd.delay 0.01 Iterate on the object to retrieve/advance the delay values. >>> next(bd) 0.01 >>> next(bd) 0.015 >>> import itertools >>> tuple(itertools.islice(bd, 3)) (0.015, 0.015, 0.015) Limit may be a callable taking a number and returning the limited number. >>> at_least_one = lambda n: max(n, 1) >>> bd = BackoffDelay(delay=0.01, factor=2, limit=at_least_one) >>> next(bd) 0.01 >>> next(bd) 1 Pass a jitter to add or subtract seconds to the delay. >>> bd = BackoffDelay(jitter=0.01) >>> next(bd) 0 >>> next(bd) 0.01 Jitter may be a callable. To supply a non-deterministic jitter between -0.5 and 0.5, consider: >>> import random >>> jitter=functools.partial(random.uniform, -0.5, 0.5) >>> bd = BackoffDelay(jitter=jitter) >>> next(bd) 0 >>> 0 <= next(bd) <= 0.5 True """ delay = 0 factor = 1 "Multiplier applied to delay" jitter = 0 "Number or callable returning extra seconds to add to delay" @jaraco.functools.save_method_args def __init__(self, delay=0, factor=1, limit=float('inf'), jitter=0): self.delay = delay self.factor = factor if isinstance(limit, numbers.Number): limit_ = limit def limit(n): return max(0, min(limit_, n)) self.limit = limit if isinstance(jitter, numbers.Number): jitter_ = jitter def jitter(): return jitter_ self.jitter = jitter def __call__(self): time.sleep(next(self)) def __next__(self): delay = self.delay self.bump() return delay def __iter__(self): return self def bump(self): self.delay = self.limit(self.delay * self.factor + self.jitter()) def reset(self): saved = self._saved___init__ self.__init__(*saved.args, **saved.kwargs) tempora-5.7.0/tempora/utc.py000066400000000000000000000017641465050464100160230ustar00rootroot00000000000000""" Facilities for common time operations in UTC. Inspired by the `utc project `_. >>> dt = now() >>> dt == fromtimestamp(dt.timestamp()) True >>> dt.tzinfo datetime.timezone.utc >>> from time import time as timestamp >>> now().timestamp() - timestamp() < 0.1 True >>> (now() - fromtimestamp(timestamp())).total_seconds() < 0.1 True >>> datetime(2018, 6, 26, 0).tzinfo datetime.timezone.utc >>> time(0, 0).tzinfo datetime.timezone.utc Now should be affected by freezegun. >>> freezer = getfixture('freezer') >>> freezer.move_to('1999-12-31 17:00:00 -0700') >>> print(now()) 2000-01-01 00:00:00+00:00 """ import datetime as std import functools __all__ = ['now', 'fromtimestamp', 'datetime', 'time'] def now(): return std.datetime.now(std.timezone.utc) fromtimestamp = functools.partial(std.datetime.fromtimestamp, tz=std.timezone.utc) datetime = functools.partial(std.datetime, tzinfo=std.timezone.utc) time = functools.partial(std.time, tzinfo=std.timezone.utc) tempora-5.7.0/tests/000077500000000000000000000000001465050464100143415ustar00rootroot00000000000000tempora-5.7.0/tests/compat/000077500000000000000000000000001465050464100156245ustar00rootroot00000000000000tempora-5.7.0/tests/compat/py38.py000066400000000000000000000002131465050464100167750ustar00rootroot00000000000000import sys if sys.version_info >= (3, 9): import zoneinfo else: # pragma: no cover from backports import zoneinfo # noqa: F401 tempora-5.7.0/tests/test_schedule.py000066400000000000000000000121211465050464100175430ustar00rootroot00000000000000import time import random import datetime from unittest import mock import pytest import freezegun from tempora import schedule from .compat.py38 import zoneinfo do_nothing = type(None) def test_delayed_command_order(): """ delayed commands should be sorted by delay time """ delays = [random.randint(0, 99) for x in range(5)] cmds = sorted(schedule.DelayedCommand.after(delay, do_nothing) for delay in delays) assert [c.delay.seconds for c in cmds] == sorted(delays) def test_periodic_command_delay(): "A PeriodicCommand must have a positive, non-zero delay." with pytest.raises(ValueError) as exc_info: schedule.PeriodicCommand.after(0, None) assert str(exc_info.value) == test_periodic_command_delay.__doc__ def test_periodic_command_fixed_delay(): """ Test that we can construct a periodic command with a fixed initial delay. """ fd = schedule.PeriodicCommandFixedDelay.at_time( at=schedule.now(), delay=datetime.timedelta(seconds=2), target=lambda: None ) assert fd.due() is True assert fd.next().due() is False class TestCommands: def test_delayed_command_from_timestamp(self): """ Ensure a delayed command can be constructed from a timestamp. """ t = time.time() schedule.DelayedCommand.at_time(t, do_nothing) def test_command_at_noon(self): """ Create a periodic command that's run at noon every day. """ when = datetime.time(12, 0, tzinfo=zoneinfo.ZoneInfo('UTC')) cmd = schedule.PeriodicCommandFixedDelay.daily_at(when, target=None) assert cmd.due() is False next_cmd = cmd.next() daily = datetime.timedelta(days=1) day_from_now = schedule.now() + daily two_days_from_now = day_from_now + daily assert day_from_now < next_cmd < two_days_from_now @pytest.mark.parametrize("hour", range(10, 14)) @pytest.mark.parametrize("tz_offset", (14, -14)) def test_command_at_noon_distant_local(self, hour, tz_offset): """ Run test_command_at_noon, but with the local timezone more than 12 hours away from UTC. """ with freezegun.freeze_time(f"2020-01-10 {hour:02}:01", tz_offset=tz_offset): self.test_command_at_noon() class TestTimezones: def test_alternate_timezone_west(self): target_tz = zoneinfo.ZoneInfo('US/Pacific') target = schedule.now().astimezone(target_tz) cmd = schedule.DelayedCommand.at_time(target, target=None) assert cmd.due() def test_alternate_timezone_east(self): target_tz = zoneinfo.ZoneInfo('Europe/Amsterdam') target = schedule.now().astimezone(target_tz) cmd = schedule.DelayedCommand.at_time(target, target=None) assert cmd.due() def test_daylight_savings(self): """ A command at 9am should always be 9am regardless of a DST boundary. """ with freezegun.freeze_time('2018-03-10'): target_tz = zoneinfo.ZoneInfo('US/Eastern') target_time = datetime.time(9, tzinfo=target_tz) cmd = schedule.PeriodicCommandFixedDelay.daily_at( target_time, target=lambda: None ) assert not cmd.due() def naive(dt): return dt.replace(tzinfo=None) assert naive(cmd) == datetime.datetime(2018, 3, 10, 9, 0, 0) with freezegun.freeze_time('2018-03-10 8:59:59 -0500'): assert not cmd.due() with freezegun.freeze_time('2018-03-10 9:00:00 -0500'): assert cmd.due() next_ = cmd.next() assert naive(next_) == datetime.datetime(2018, 3, 11, 9, 0, 0) with freezegun.freeze_time('2018-03-11 8:59:59 -0400'): assert not next_.due() with freezegun.freeze_time('2018-03-11 9:00:00 -0400'): assert next_.due() class TestScheduler: def test_invoke_scheduler(self): sched = schedule.InvokeScheduler() target = mock.MagicMock() cmd = schedule.DelayedCommand.after(0, target) sched.add(cmd) sched.run_pending() target.assert_called_once() assert not sched.queue def test_callback_scheduler(self): callback = mock.MagicMock() sched = schedule.CallbackScheduler(callback) target = mock.MagicMock() cmd = schedule.DelayedCommand.after(0, target) sched.add(cmd) sched.run_pending() callback.assert_called_once_with(target) def test_periodic_command(self): sched = schedule.InvokeScheduler() target = mock.MagicMock() before = datetime.datetime.now(tz=datetime.timezone.utc) cmd = schedule.PeriodicCommand.after(10, target) sched.add(cmd) sched.run_pending() target.assert_not_called() with freezegun.freeze_time(before + datetime.timedelta(seconds=15)): sched.run_pending() assert sched.queue target.assert_called_once() with freezegun.freeze_time(before + datetime.timedelta(seconds=25)): sched.run_pending() assert target.call_count == 2 tempora-5.7.0/tests/test_timing.py000066400000000000000000000023671465050464100172510ustar00rootroot00000000000000import datetime import time import contextlib import os from unittest import mock import pytest from tempora import timing def test_IntervalGovernor(): """ IntervalGovernor should prevent a function from being called more than once per interval. """ func_under_test = mock.MagicMock() # to look like a function, it needs a __name__ attribute func_under_test.__name__ = 'func_under_test' interval = datetime.timedelta(seconds=1) governed = timing.IntervalGovernor(interval)(func_under_test) governed('a') governed('b') governed(3, 'sir') func_under_test.assert_called_once_with('a') @pytest.fixture def alt_tz(monkeypatch): hasattr(time, 'tzset') or pytest.skip("tzset not available") @contextlib.contextmanager def change(): val = 'AEST-10AEDT-11,M10.5.0,M3.5.0' with monkeypatch.context() as ctx: ctx.setitem(os.environ, 'TZ', val) time.tzset() yield time.tzset() return change() def test_Stopwatch_timezone_change(alt_tz): """ The stopwatch should provide a consistent duration even if the timezone changes. """ watch = timing.Stopwatch() with alt_tz: assert abs(watch.split().total_seconds()) < 0.1 tempora-5.7.0/towncrier.toml000066400000000000000000000000541465050464100161070ustar00rootroot00000000000000[tool.towncrier] title_format = "{version}" tempora-5.7.0/tox.ini000066400000000000000000000025151465050464100145150ustar00rootroot00000000000000[testenv] description = perform primary checks (tests, style, types, coverage) deps = setenv = PYTHONWARNDEFAULTENCODING = 1 commands = pytest {posargs} usedevelop = True extras = test [testenv:diffcov] description = run tests and check that diff from main is covered deps = {[testenv]deps} diff-cover commands = pytest {posargs} --cov-report xml diff-cover coverage.xml --compare-branch=origin/main --html-report diffcov.html diff-cover coverage.xml --compare-branch=origin/main --fail-under=100 [testenv:docs] description = build the documentation extras = doc test changedir = docs commands = python -m sphinx -W --keep-going . {toxinidir}/build/html python -m sphinxlint \ # workaround for sphinx-contrib/sphinx-lint#83 --jobs 1 [testenv:finalize] description = assemble changelog and tag a release skip_install = True deps = towncrier jaraco.develop >= 7.23 pass_env = * commands = python -m jaraco.develop.finalize [testenv:release] description = publish the package to PyPI and GitHub skip_install = True deps = build twine>=3 jaraco.develop>=7.1 pass_env = TWINE_PASSWORD GITHUB_TOKEN setenv = TWINE_USERNAME = {env:TWINE_USERNAME:__token__} commands = python -c "import shutil; shutil.rmtree('dist', ignore_errors=True)" python -m build python -m twine upload dist/* python -m jaraco.develop.create-github-release