PyOTP 2.10.0__tar.gz → 2.11.1__tar.gz

pyotp-2.11.1/.github/workflows/actions.lock

@@ -0,0 +1,64 @@
+# This file is machine-generated by `gh actions-lock`.
+# Do not edit by hand; run `gh actions-lock` to update.
+# Docs: https://gh.io/actions-lockfile
+version: 'v0.0.3'
+workflows:
+    '.github/workflows/ci.yml':
+        - 'actions/checkout@v7'
+        - 'actions/setup-python@v7'
+        - 'astral-sh/ruff-action@v4.1.0'
+        - 'codecov/codecov-action@v7'
+    '.github/workflows/release.yml':
+        - 'actions/checkout@v4'
+        - 'actions/setup-python@v5'
+        - 'pypa/gh-action-pypi-publish@release/v1'
+dependencies:
+    'actions/checkout@v4':
+        ref: 'v4'
+        commit: 'sha1-11d5960a326750d5838078e36cf38b85af677262'
+        owner_id: 44036562
+        repo_id: 197814629
+    'actions/checkout@v7':
+        ref: 'v7'
+        commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
+        owner_id: 44036562
+        repo_id: 197814629
+    'actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd':
+        ref: 'v8.0.0'
+        commit: 'sha1-ed597411d8f924073f98dfc5c65a23a2325f34cd'
+        owner_id: 44036562
+        repo_id: 205262760
+    'actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405':
+        ref: 'v6.2.0'
+        commit: 'sha1-a309ff8b426b58ec0e2a45f0f869d46889d02405'
+        owner_id: 44036562
+        repo_id: 192625525
+    'actions/setup-python@v5':
+        ref: 'v5'
+        commit: 'sha1-a26af69be951a213d495a4c3e4e4022e16d87065'
+        owner_id: 44036562
+        repo_id: 192625525
+    'actions/setup-python@v7':
+        ref: 'v7'
+        commit: 'sha1-6d4fd22b20465ccc0f7354476588e8df7c9ca0e0'
+        owner_id: 44036562
+        repo_id: 192625525
+    'astral-sh/ruff-action@v4.1.0':
+        ref: 'v4.1.0'
+        commit: 'sha1-278981a28ce3188b1e39527901f38254bf3aac89'
+        owner_id: 115962839
+        repo_id: 865075538
+    'codecov/codecov-action@v7':
+        ref: 'v7'
+        commit: 'sha1-303a32d7a59b442fa8d48b6a1cc6825c09c847a5'
+        owner_id: 8226205
+        repo_id: 200299178
+        uses:
+            - 'actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd'
+    'pypa/gh-action-pypi-publish@release/v1':
+        ref: 'release/v1'
+        commit: 'sha1-7245906fb61fa33a13554f9d5fb856fe61758086'
+        owner_id: 647025
+        repo_id: 178055147
+        uses:
+            - 'actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405'

{pyotp-2.10.0 → pyotp-2.11.1}/.github/workflows/ci.yml

@@ -10,22 +10,22 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-22.04, ubuntu-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v7
       with:
         python-version: ${{ matrix.python-version }}
     - run: make install
     - run: make lint
     - run: make test
-    - uses: codecov/codecov-action@v5
+    - uses: codecov/codecov-action@v7
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/ruff-action@v3
-      - uses: astral-sh/ruff-action@v3
+      - uses: actions/checkout@v7
+      - uses: astral-sh/ruff-action@v4.1.0
+      - uses: astral-sh/ruff-action@v4.1.0
         with:
           args: "format --check"

{pyotp-2.10.0 → pyotp-2.11.1}/Changes.rst

@@ -1,3 +1,19 @@
+Changes for v2.11.1 (2026-11-14)
+================================
+
+-  Fix PyPI README markup and validate distributions before release
+   (#200)
+
+Changes for v2.11.0 (2026-11-14)
+================================
+
+-  Fix DST rollbacks and normalize TOTP timestamp inputs (#197)
+
+-  Respect initial_count=0 in HOTP.provisioning_uri() (#190)
+
+-  Implement verify_and_get_timecode, a method for TOTP that verifies
+   and returns the matching timecode (#191)
+
 Changes for v2.10.0 (2026-06-13)
 ================================
 

{pyotp-2.10.0 → pyotp-2.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: PyOTP
-Version: 2.10.0
+Version: 2.11.1
 Summary: Python One Time Password Library
 Project-URL: Homepage, https://github.com/pyauth/pyotp
 Project-URL: Documentation, https://github.com/pyauth/pyotp
@@ -96,7 +96,7 @@ Usage
 
 Time-based OTPs
 ~~~~~~~~~~~~~~~
-::
+.. code:: python
 
     import pyotp
     import time
@@ -111,7 +111,7 @@ Time-based OTPs
 
 Counter-based OTPs
 ~~~~~~~~~~~~~~~~~~
-::
+.. code:: python
 
     import pyotp
     
@@ -127,11 +127,15 @@ Counter-based OTPs
 Generating a Secret Key
 ~~~~~~~~~~~~~~~~~~~~~~~
 A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other
-OTP apps::
+OTP apps:
+
+.. code:: python
 
     pyotp.random_base32()
 
-Some applications want the secret key to be formatted as a hex-encoded string::
+Some applications want the secret key to be formatted as a hex-encoded string:
+
+.. code:: python
 
     pyotp.random_hex()  # returns a 40-character hex-encoded secret
 
@@ -139,7 +143,9 @@ Google Authenticator Compatible
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes
-the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps::
+the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:
+
+.. code:: python
 
     pyotp.totp.TOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name='alice@google.com', issuer_name='Secure App')
 
@@ -152,7 +158,9 @@ the ability to generate provisioning URIs for use with the QR Code scanner built
 This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be
 scanned and added to the users list of OTP credentials.
 
-Parsing these URLs is also supported::
+Parsing these URLs is also supported:
+
+.. code:: python
 
     pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App')
 
@@ -169,7 +177,9 @@ Scan the following barcode with your phone's OTP app (e.g. Google Authenticator)
 
 .. image:: https://quickchart.io/qr?size=250&text=otpauth%3A%2F%2Ftotp%2Falice%40google.com%3Fsecret%3DJBSWY3DPEHPK3PXP
 
-Now run the following and compare the output::
+Now run the following and compare the output:
+
+.. code:: python
 
     import pyotp
     totp = pyotp.TOTP("JBSWY3DPEHPK3PXP")

{pyotp-2.10.0 → pyotp-2.11.1}/README.rst

@@ -57,7 +57,7 @@ Usage
 
 Time-based OTPs
 ~~~~~~~~~~~~~~~
-::
+.. code:: python
 
     import pyotp
     import time
@@ -72,7 +72,7 @@ Time-based OTPs
 
 Counter-based OTPs
 ~~~~~~~~~~~~~~~~~~
-::
+.. code:: python
 
     import pyotp
     
@@ -88,11 +88,15 @@ Counter-based OTPs
 Generating a Secret Key
 ~~~~~~~~~~~~~~~~~~~~~~~
 A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other
-OTP apps::
+OTP apps:
+
+.. code:: python
 
     pyotp.random_base32()
 
-Some applications want the secret key to be formatted as a hex-encoded string::
+Some applications want the secret key to be formatted as a hex-encoded string:
+
+.. code:: python
 
     pyotp.random_hex()  # returns a 40-character hex-encoded secret
 
@@ -100,7 +104,9 @@ Google Authenticator Compatible
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes
-the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps::
+the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:
+
+.. code:: python
 
     pyotp.totp.TOTP('JBSWY3DPEHPK3PXP').provisioning_uri(name='alice@google.com', issuer_name='Secure App')
 
@@ -113,7 +119,9 @@ the ability to generate provisioning URIs for use with the QR Code scanner built
 This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be
 scanned and added to the users list of OTP credentials.
 
-Parsing these URLs is also supported::
+Parsing these URLs is also supported:
+
+.. code:: python
 
     pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXP&issuer=Secure%20App')
 
@@ -130,7 +138,9 @@ Scan the following barcode with your phone's OTP app (e.g. Google Authenticator)
 
 .. image:: https://quickchart.io/qr?size=250&text=otpauth%3A%2F%2Ftotp%2Falice%40google.com%3Fsecret%3DJBSWY3DPEHPK3PXP
 
-Now run the following and compare the output::
+Now run the following and compare the output:
+
+.. code:: python
 
     import pyotp
     totp = pyotp.TOTP("JBSWY3DPEHPK3PXP")

{pyotp-2.10.0 → pyotp-2.11.1}/common.mk

@@ -13,12 +13,15 @@ release-patch:
 	$(MAKE) release
 
 release:
+	@if [[ "$$(git symbolic-ref --quiet HEAD)" != refs/heads/main ]]; then echo "Releases must be run from the main branch"; exit 1; fi
 	@if ! git diff --cached --exit-code; then echo "Commit staged files before proceeding"; exit 1; fi
+	@if ! git diff --exit-code; then echo "Commit unstaged changes before proceeding"; exit 1; fi
 	@if [[ -z $$TAG ]]; then echo "Use release-{major,minor,patch}"; exit 1; fi
 	@if ! type -P pandoc; then echo "Please install pandoc"; exit 1; fi
 	@if ! type -P sponge; then echo "Please install moreutils"; exit 1; fi
 	@if ! type -P gh; then echo "Please install gh"; exit 1; fi
 	git pull
+	$(MAKE) check-dist
 	TAG_MSG=$$(mktemp); \
 	    echo "# Changes for ${TAG} ($$(date +%Y-%m-%d))" > $$TAG_MSG; \
 	    git log --pretty=format:%s $$(git describe --abbrev=0)..HEAD >> $$TAG_MSG; \
@@ -32,6 +35,13 @@ release:
 	gh release create ${TAG} dist/*.whl --notes="$$(git tag --list ${TAG} -n99 | perl -pe 's/^\S+\s*// if $$. == 1' | sed 's/^\s\s\s\s//')"
 	$(MAKE) release-docs
 
+check-dist:
+	@python -c 'import build, twine' 2>/dev/null || { echo "Please install build and twine: python -m pip install build twine"; exit 1; }
+	@release_dist_dir=$$(mktemp -d); \
+	    trap 'rm -rf "$$release_dist_dir"' EXIT; \
+	    python -m build --outdir "$$release_dist_dir"; \
+	    python -m twine check --strict "$$release_dist_dir"/*
+
 release-docs:
 	$(MAKE) docs
 	-git branch -D gh-pages
@@ -42,4 +52,4 @@ release-docs:
 	git push --force origin $$(git subtree split --prefix docs/html --branch gh-pages):refs/heads/gh-pages
 	git checkout -
 
-.PHONY: release
+.PHONY: release check-dist

{pyotp-2.10.0 → pyotp-2.11.1}/pyproject.toml

@@ -53,3 +53,14 @@ line_length = 120
 
 [tool.ruff]
 line-length = 120
+
+[tool.ruff.lint]
+ignore = [
+    "SIM102",  # Allow nested if statements.
+    "SIM117",  # Allow nested with statements.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]
+# Keep accepted timestamp types explicit in public API annotations.
+"src/pyotp/totp.py" = ["PYI041"]

{pyotp-2.10.0 → pyotp-2.11.1}/src/pyotp/__init__.py

@@ -1,13 +1,15 @@
+from __future__ import annotations
+
 import hashlib
 from re import split
-from typing import Any, Dict, Sequence
+from typing import Any, Sequence
 from urllib.parse import parse_qsl, unquote, urlparse
 
-from . import contrib  # noqa:F401
+from . import contrib
 from .compat import random
-from .hotp import HOTP as HOTP
-from .otp import OTP as OTP
-from .totp import TOTP as TOTP
+from .hotp import HOTP
+from .otp import OTP
+from .totp import TOTP
 
 
 def random_base32(length: int = 32, chars: Sequence[str] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567") -> str:
@@ -47,7 +49,7 @@ def parse_uri(uri: str) -> OTP:
     digits = None
 
     # Data we'll parse to the correct constructor
-    otp_data: Dict[str, Any] = {}
+    otp_data: dict[str, Any] = {}
 
     # Parse the URI structure first, then unquote individual components.
     # Unquoting the whole URI before splitting the label would turn an
@@ -97,9 +99,8 @@ def parse_uri(uri: str) -> OTP:
         elif key == "counter":
             otp_data["initial_count"] = int(value)
 
-    if encoder != "steam":
-        if digits is not None and digits not in [6, 7, 8]:
-            raise ValueError("Digits may only be 6, 7, or 8")
+    if encoder != "steam" and digits is not None and digits not in [6, 7, 8]:
+        raise ValueError("Digits may only be 6, 7, or 8")
 
     if not secret:
         raise ValueError("No secret found in URI")

pyotp-2.11.1/src/pyotp/compat.py

@@ -0,0 +1,3 @@
+from secrets import SystemRandom
+
+random = SystemRandom()

pyotp-2.11.1/src/pyotp/contrib/__init__.py

@@ -0,0 +1 @@
+from .steam import Steam

{pyotp-2.10.0 → pyotp-2.11.1}/src/pyotp/contrib/steam.py

@@ -1,5 +1,6 @@
+from __future__ import annotations
+
 import hashlib
-from typing import Optional
 
 from ..totp import TOTP
 
@@ -13,7 +14,7 @@ class Steam(TOTP):
     """
 
     def __init__(
-        self, s: str, name: Optional[str] = None, issuer: Optional[str] = None, interval: int = 30, digits: int = 5
+        self, s: str, name: str | None = None, issuer: str | None = None, interval: int = 30, digits: int = 5
     ) -> None:
         """
         :param s: secret in base32 format

{pyotp-2.10.0 → pyotp-2.11.1}/src/pyotp/hotp.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import hashlib
-from typing import Any, Optional
+from typing import Any
 
 from . import utils
 from .otp import OTP
@@ -15,8 +17,8 @@ class HOTP(OTP):
         s: str,
         digits: int = 6,
         digest: Any = None,
-        name: Optional[str] = None,
-        issuer: Optional[str] = None,
+        name: str | None = None,
+        issuer: str | None = None,
         initial_count: int = 0,
     ) -> None:
         """
@@ -55,9 +57,9 @@ class HOTP(OTP):
 
     def provisioning_uri(
         self,
-        name: Optional[str] = None,
-        initial_count: Optional[int] = None,
-        issuer_name: Optional[str] = None,
+        name: str | None = None,
+        initial_count: int | None = None,
+        issuer_name: str | None = None,
         **kwargs,
     ) -> str:
         """
@@ -77,7 +79,7 @@ class HOTP(OTP):
         return utils.build_uri(
             self.secret,
             name=name if name else self.name,
-            initial_count=initial_count if initial_count else self.initial_count,
+            initial_count=initial_count if initial_count is not None else self.initial_count,
             issuer=issuer_name if issuer_name else self.issuer,
             algorithm=self.digest().name,
             digits=self.digits,

{pyotp-2.10.0 → pyotp-2.11.1}/src/pyotp/otp.py

@@ -1,10 +1,12 @@
+from __future__ import annotations
+
 import base64
 import hashlib
 import hmac
-from typing import Any, Optional
+from typing import Any
 
 
-class OTP(object):
+class OTP:
     """
     Base class for OTP handlers.
     """
@@ -14,8 +16,8 @@ class OTP(object):
         s: str,
         digits: int = 6,
         digest: Any = hashlib.sha1,
-        name: Optional[str] = None,
-        issuer: Optional[str] = None,
+        name: str | None = None,
+        issuer: str | None = None,
     ) -> None:
         self.digits = digits
         if digits > 10:
@@ -69,4 +71,4 @@ class OTP(object):
         # It's necessary to convert the final result from bytearray to bytes
         # because the hmac functions in python 2.6 and 3.3 don't work with
         # bytearray
-        return bytes(bytearray(reversed(result)).rjust(padding, b"\0"))
+        return bytes(reversed(result.ljust(padding, b"\0")))

pyotp-2.11.1/src/pyotp/totp.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import calendar
+import datetime
+import hashlib
+import time
+from typing import Any, Literal
+
+from . import utils
+from .otp import OTP
+
+_TIMESTAMP_LIMIT = 253402300800  # 10000-01-01 00:00:00 UTC, exclusive.
+
+
+class TOTP(OTP):
+    """
+    Handler for time-based OTP counters.
+    """
+
+    def __init__(
+        self,
+        s: str,
+        digits: int = 6,
+        digest: Any = None,
+        name: str | None = None,
+        issuer: str | None = None,
+        interval: int = 30,
+    ) -> None:
+        """
+        :param s: secret in base32 format
+        :param digits: number of integers in the OTP. Some apps expect this to be 6 digits, others support more.
+        :param digest: digest function to use in the HMAC (expected to be SHA1)
+        :param name: account name
+        :param issuer: issuer
+        :param interval: the time interval in seconds for OTP. This defaults to 30.
+        """
+        if digest is None:
+            digest = hashlib.sha1
+        elif digest in [hashlib.md5, hashlib.shake_128]:
+            raise ValueError("selected digest function must generate digest size greater than or equals to 18 bytes")
+
+        self.interval = interval
+        super().__init__(s=s, digits=digits, digest=digest, name=name, issuer=issuer)
+
+    def at(self, for_time: int | float | datetime.datetime, counter_offset: int = 0) -> str:
+        """
+        Accepts a Unix timestamp (int or float) or a datetime object.
+
+        Unix timestamps are measured in seconds since 1970-01-01 00:00:00 UTC.
+        Prefer Unix timestamps or timezone-aware UTC datetimes. Naive
+        datetimes are interpreted as local time, respecting ``fold``.
+
+        To get the time until the next timecode change (seconds until the current OTP expires), use this instead:
+
+        .. code:: python
+
+            totp = pyotp.TOTP(...)
+            time_remaining = totp.interval - time.time() % totp.interval
+
+        :param for_time: the time to generate an OTP for
+        :param counter_offset: the amount of ticks to add to the time counter
+        :returns: OTP value
+        :raises ValueError: if for_time is before the Unix epoch or after year 9999 in UTC
+        """
+        return self.generate_otp(self.timecode(for_time) + counter_offset)
+
+    def now(self) -> str:
+        """
+        Generate the current time OTP
+
+        :returns: OTP value
+        :raises ValueError: if the current time is before the Unix epoch or after year 9999 in UTC
+        """
+        return self.generate_otp(self.timecode(time.time()))
+
+    def verify(self, otp: str, for_time: int | float | datetime.datetime | None = None, valid_window: int = 0) -> bool:
+        """
+        Verifies the OTP passed in against the current time OTP.
+
+        Unix timestamps are measured in seconds since 1970-01-01 00:00:00 UTC.
+        Prefer Unix timestamps or timezone-aware UTC datetimes. Naive
+        datetimes are interpreted as local time, respecting ``fold``.
+
+        :param otp: the OTP to check against
+        :param for_time: Unix timestamp (int or float) or datetime to check OTP at (defaults to now)
+        :param valid_window: extends the validity to this many counter ticks before and after the current one
+        :returns: True if verification succeeded, False otherwise
+        :raises ValueError: if for_time is before the Unix epoch or after year 9999 in UTC
+        """
+        if for_time is None:
+            for_time = time.time()
+
+        timecode = self.timecode(for_time)
+
+        if valid_window:
+            for i in range(-valid_window, valid_window + 1):
+                if utils.strings_equal(str(otp), str(self.generate_otp(timecode + i))):
+                    return True
+            return False
+
+        return utils.strings_equal(str(otp), str(self.generate_otp(timecode)))
+
+    def verify_and_get_timecode(
+        self, otp: str, for_time: int | float | datetime.datetime | None = None, valid_window: int = 0
+    ) -> int | Literal[False]:
+        """
+        Verifies the OTP passed in against the current time OTP and returns the matching timecode.
+
+        This is useful when callers need to prevent TOTP reuse. An
+        application can store the timecode from the last successful
+        authentication and reject future OTPs whose matching timecode
+        is not greater than the stored one.
+
+        Unix timestamps are measured in seconds since 1970-01-01 00:00:00 UTC.
+        Prefer Unix timestamps or timezone-aware UTC datetimes. Naive
+        datetimes are interpreted as local time, respecting ``fold``.
+
+        :param otp: the OTP to check against
+        :param for_time: Unix timestamp (int or float) or datetime to check OTP at (defaults to now)
+        :param valid_window: extends the validity to this counter ticks before and after the current one
+        :returns: matching timecode if verification succeeded, False otherwise
+        :raises ValueError: if for_time is before the Unix epoch or after year 9999 in UTC
+        """
+        if for_time is None:
+            for_time = time.time()
+
+        if valid_window < 0:
+            raise ValueError("valid_window cannot be negative")
+
+        timecode = self.timecode(for_time)
+        for i in range(-valid_window, valid_window + 1):
+            if utils.strings_equal(str(otp), str(self.generate_otp(timecode + i))):
+                return timecode + i
+        return False
+
+    def provisioning_uri(self, name: str | None = None, issuer_name: str | None = None, **kwargs) -> str:
+        """
+        Returns the provisioning URI for the OTP.  This can then be
+        encoded in a QR Code and used to provision an OTP app like
+        Google Authenticator.
+
+        See also:
+            https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+
+        """
+        return utils.build_uri(
+            self.secret,
+            name if name else self.name,
+            issuer=issuer_name if issuer_name else self.issuer,
+            algorithm=self.digest().name,
+            digits=self.digits,
+            period=self.interval,
+            **kwargs,
+        )
+
+    def timecode(self, for_time: int | float | datetime.datetime) -> int:
+        """
+        Converts a Unix timestamp (int or float) or a datetime object
+        to the corresponding counter value (timecode).
+
+        Unix timestamps are measured in seconds since 1970-01-01 00:00:00 UTC.
+        Prefer Unix timestamps or timezone-aware UTC datetimes. Naive
+        datetimes are interpreted as local time, using ``fold`` to
+        distinguish repeated clock times. Subsecond precision is ignored.
+
+        :raises ValueError: if for_time is before the Unix epoch or after year 9999 in UTC
+        """
+        error_message = "for_time must be at or after the Unix epoch and before year 10000 UTC"
+        timestamp: int | float
+        if isinstance(for_time, datetime.datetime):
+            try:
+                if for_time.tzinfo:
+                    timestamp = calendar.timegm(for_time.utctimetuple())
+                else:
+                    # Preserve whole-second behavior without discarding fold.
+                    timestamp = for_time.replace(microsecond=0).timestamp()
+            except (OverflowError, OSError, ValueError) as error:
+                raise ValueError(error_message) from error
+        else:
+            timestamp = for_time
+        if not 0 <= timestamp < _TIMESTAMP_LIMIT:
+            raise ValueError(error_message)
+        return int(int(timestamp) / self.interval)

{pyotp-2.10.0 → pyotp-2.11.1}/src/pyotp/utils.py

@@ -1,17 +1,18 @@
+from __future__ import annotations
+
 import unicodedata
 from hmac import compare_digest
-from typing import Dict, Optional, Union
 from urllib.parse import quote, urlencode, urlparse
 
 
 def build_uri(
     secret: str,
     name: str,
-    initial_count: Optional[int] = None,
-    issuer: Optional[str] = None,
-    algorithm: Optional[str] = None,
-    digits: Optional[int] = None,
-    period: Optional[int] = None,
+    initial_count: int | None = None,
+    issuer: str | None = None,
+    algorithm: str | None = None,
+    digits: int | None = None,
+    period: int | None = None,
     **kwargs,
 ) -> str:
     """
@@ -49,7 +50,7 @@ def build_uri(
     otp_type = "hotp" if is_initial_count_present else "totp"
     base_uri = "otpauth://{0}/{1}?{2}"
 
-    url_args: Dict[str, Union[None, int, str]] = {"secret": secret}
+    url_args: dict[str, None | int | str] = {"secret": secret}
 
     label = quote(name)
     if issuer is not None:
@@ -66,11 +67,11 @@ def build_uri(
         url_args["period"] = period
     for k, v in kwargs.items():
         if not isinstance(v, str):
-            raise ValueError("All otpauth uri parameters must be strings")
+            raise TypeError("All otpauth uri parameters must be strings")
         if k == "image":
             image_uri = urlparse(v)
             if image_uri.scheme != "https" or not image_uri.netloc or not image_uri.path:
-                raise ValueError("{} is not a valid url".format(image_uri))
+                raise ValueError(f"{image_uri} is not a valid url")
         url_args[k] = v
 
     uri = base_uri.format(otp_type, label, urlencode(url_args).replace("+", "%20"))

{pyotp-2.10.0 → pyotp-2.11.1}/test.py

@@ -5,12 +5,15 @@ import datetime
 import hashlib
 import os
 import sys
+import time
 import unittest
+from typing import ClassVar
+from unittest.mock import patch
 from urllib.parse import parse_qsl, urlparse
 from warnings import warn
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))
-import pyotp  # noqa
+import pyotp
 
 
 class HOTPExampleValuesFromTheRFC(unittest.TestCase):
@@ -97,6 +100,11 @@ class HOTPExampleValuesFromTheRFC(unittest.TestCase):
         )
         self.assertEqual(hotp.provisioning_uri(), pyotp.parse_uri(hotp.provisioning_uri()).provisioning_uri())
 
+        # initial_count=0 must be respected even though 0 is falsy
+        hotp = pyotp.HOTP("wrn3pqx5uqxqvnqr", name="mark@percival", initial_count=7)
+        url = urlparse(hotp.provisioning_uri(initial_count=0))
+        self.assertEqual(dict(parse_qsl(url.query))["counter"], "0")
+
         code = pyotp.totp.TOTP("S46SQCPPTCNPROMHWYBDCTBZXV")
         self.assertEqual(code.provisioning_uri(), "otpauth://totp/Secret?secret=S46SQCPPTCNPROMHWYBDCTBZXV")
         code.verify("123456")
@@ -112,7 +120,7 @@ class HOTPExampleValuesFromTheRFC(unittest.TestCase):
 
 
 class TOTPExampleValuesFromTheRFC(unittest.TestCase):
-    RFC_VALUES = {
+    RFC_VALUES: ClassVar[dict] = {
         (hashlib.sha1, b"12345678901234567890"): (
             (59, "94287082"),
             (1111111109, "07081804"),
@@ -175,11 +183,10 @@ class TOTPExampleValuesFromTheRFC(unittest.TestCase):
 
     def test_input_before_epoch(self):
         totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
-        # -1 and -29.5 round down to 0 (epoch)
-        self.assertEqual(totp.at(-1), "755224")
-        self.assertEqual(totp.at(-29.5), "755224")
-        with self.assertRaises(ValueError):
-            totp.at(-30)
+        for timestamp in (-30, -29.5, -1, -0.1):
+            with self.subTest(timestamp=timestamp):
+                with self.assertRaises(ValueError):
+                    totp.at(timestamp)
 
     def test_validate_totp_with_digit_length(self):
         totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
@@ -245,6 +252,15 @@ class TOTPExampleValuesFromTheRFC(unittest.TestCase):
         )
         self.assertEqual(totp.provisioning_uri(), pyotp.parse_uri(totp.provisioning_uri()).provisioning_uri())
 
+    def test_provisioning_uri_parameter_types(self):
+        for otp_type in (pyotp.TOTP, pyotp.HOTP):
+            with self.subTest(otp_type=otp_type):
+                otp = otp_type("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+                with self.assertRaises(TypeError):
+                    otp.provisioning_uri(image=123)
+                with self.assertRaises(ValueError):
+                    otp.provisioning_uri(image="not-a-url")
+
     def test_random_key_generation(self):
         self.assertEqual(len(pyotp.random_base32()), 32)
         self.assertEqual(len(pyotp.random_base32(length=34)), 34)
@@ -256,6 +272,209 @@ class TOTPExampleValuesFromTheRFC(unittest.TestCase):
             pyotp.random_hex(length=39)
 
 
+@unittest.skipUnless(hasattr(time, "tzset"), "Local timezone tests require time.tzset()")
+class TOTPTimezones(unittest.TestCase):
+    def setUp(self):
+        self.original_tz = os.environ.get("TZ")
+        self.addCleanup(self.restore_timezone)
+
+    def restore_timezone(self):
+        if self.original_tz is None:
+            os.environ.pop("TZ", None)
+        else:
+            os.environ["TZ"] = self.original_tz
+        time.tzset()
+
+    def test_repeated_local_times(self):
+        # POSIX rules keep these tests independent of the installed timezone database.
+        transitions = (
+            ("GMT0BST,M3.5.0/1,M10.5.0/2", "2026-10-25T00:30:00+00:00", "2026-10-25T01:30:00+00:00"),
+            ("EST5EDT,M3.2.0/2,M11.1.0/2", "2026-11-01T05:30:00+00:00", "2026-11-01T06:30:00+00:00"),
+            ("LHST-10:30LHDT-11,M10.1.0/2,M4.1.0/2", "2026-04-04T14:45:00+00:00", "2026-04-04T15:15:00+00:00"),
+        )
+        for timezone, first, second in transitions:
+            os.environ["TZ"] = timezone
+            time.tzset()
+            timestamps = [int(datetime.datetime.fromisoformat(value).timestamp()) for value in (first, second)]
+            local_times = [datetime.datetime.fromtimestamp(ts, datetime.timezone.utc).astimezone() for ts in timestamps]
+            self.assertEqual(local_times[0].replace(tzinfo=None), local_times[1].replace(tzinfo=None))
+            self.assertNotEqual(local_times[0].utcoffset(), local_times[1].utcoffset())
+            for fold, timestamp in enumerate(timestamps):
+                for otp_type in (pyotp.TOTP, pyotp.contrib.Steam):
+                    for interval in (30, 60) if otp_type is pyotp.TOTP else (30,):
+                        totp = otp_type("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ", interval=interval)
+                        for delta in (-1, 0, 1):
+                            with self.subTest(
+                                timezone=timezone, fold=fold, otp=otp_type, interval=interval, delta=delta
+                            ):
+                                ts = timestamp + delta
+                                counter = ts // interval
+                                expected = totp.generate_otp(counter)
+                                aware = datetime.datetime.fromtimestamp(ts, datetime.timezone.utc).astimezone()
+                                naive = aware.replace(tzinfo=None, fold=fold)
+                                for for_time in (ts, ts + 0.5, naive, aware):
+                                    self.assertEqual(totp.timecode(for_time), counter)
+                                    self.assertEqual(totp.at(for_time), expected)
+                                    self.assertTrue(totp.verify(expected, for_time))
+                                    self.assertEqual(totp.verify_and_get_timecode(expected, for_time), counter)
+                                    for offset in (-1, 1):
+                                        adjacent = totp.generate_otp(counter + offset)
+                                        self.assertEqual(totp.at(for_time, offset), adjacent)
+                                        self.assertTrue(totp.verify(adjacent, for_time, valid_window=1))
+                                        self.assertEqual(
+                                            totp.verify_and_get_timecode(adjacent, for_time, valid_window=1),
+                                            counter + offset,
+                                        )
+                                other = totp.generate_otp((timestamps[1 - fold] + delta) // interval)
+                                self.assertFalse(totp.verify(other, naive, valid_window=1))
+                                self.assertIs(totp.verify_and_get_timecode(other, naive, valid_window=1), False)
+                                with Timecop(ts):
+                                    self.assertEqual(datetime.datetime.now().astimezone().timestamp(), ts)
+                                    self.assertEqual(totp.now(), expected)
+                                    self.assertTrue(totp.verify(expected))
+                                    self.assertEqual(totp.verify_and_get_timecode(expected), counter)
+
+    def test_naive_fractional_seconds(self):
+        os.environ["TZ"] = "UTC0"
+        time.tzset()
+        totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+        for for_time, counter in TOTPTimecode.FRACTIONAL_SECONDS:
+            with self.subTest(for_time=for_time):
+                self.assertEqual(totp.timecode(for_time.replace(tzinfo=None)), counter)
+
+    def test_naive_time_range(self):
+        os.environ["TZ"] = "UTC0"
+        time.tzset()
+        totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+        epoch = datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc).replace(tzinfo=None)
+        self.assertEqual(totp.timecode(epoch), 0)
+        self.assertEqual(totp.timecode(datetime.datetime.max), 8446743359)
+        for for_time in (datetime.datetime.min, epoch - datetime.timedelta(microseconds=1)):
+            with self.subTest(for_time=for_time):
+                with self.assertRaisesRegex(ValueError, "for_time must be"):
+                    totp.timecode(for_time)
+                with self.assertRaises(ValueError):
+                    totp.at(for_time)
+                with self.assertRaises(ValueError):
+                    totp.verify("invalid", for_time=for_time)
+                with self.assertRaises(ValueError):
+                    totp.verify_and_get_timecode("invalid", for_time=for_time)
+
+
+class TOTPTimecode(unittest.TestCase):
+    FRACTIONAL_SECONDS = (
+        (datetime.datetime(1970, 1, 1, 0, 0, 29, 999999, tzinfo=datetime.timezone.utc), 0),
+        (datetime.datetime(1970, 1, 1, 0, 0, 30, tzinfo=datetime.timezone.utc), 1),
+        (datetime.datetime(2600, 1, 1, 0, 0, 29, 999999, tzinfo=datetime.timezone.utc), 662696640),
+    )
+
+    def test_aware_fractional_seconds(self):
+        totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+        for for_time, counter in self.FRACTIONAL_SECONDS:
+            for timezone in (datetime.timezone.utc, datetime.timezone(datetime.timedelta(hours=5, minutes=30))):
+                aware = for_time.astimezone(timezone)
+                with self.subTest(for_time=aware):
+                    self.assertEqual(totp.timecode(aware), counter)
+
+    def test_numeric_timestamps(self):
+        totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+        cases = (
+            (0, 0),
+            (29.999999, 0),
+            (30.0, 1),
+            (59.999999, 1),
+            (60, 2),
+            (253402300799, 8446743359),
+            (253402300799.5, 8446743359),
+        )
+        for timestamp, counter in cases:
+            with self.subTest(timestamp=timestamp):
+                self.assertEqual(totp.timecode(timestamp), counter)
+                code = totp.generate_otp(counter)
+                self.assertEqual(totp.at(timestamp), code)
+                self.assertTrue(totp.verify(code, for_time=timestamp))
+                matched = totp.verify_and_get_timecode(code, for_time=timestamp)
+                self.assertIsNot(matched, False)
+                self.assertEqual(matched, counter)
+
+    def test_timestamps_outside_datetime_range(self):
+        for timestamp in (-30.5, -29.5, -1, -0.1, 253402300800, 253402300800.0, 10**12):
+            self.assert_time_out_of_range(timestamp)
+
+    def test_nonfinite_timestamps(self):
+        for timestamp in (float("nan"), float("inf"), float("-inf")):
+            self.assert_time_out_of_range(timestamp)
+
+    def test_current_time_outside_range(self):
+        for otp_type in (pyotp.TOTP, pyotp.contrib.Steam):
+            totp = otp_type("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+            for timestamp in (-0.1, 253402300800):
+                with self.subTest(otp_type=otp_type, timestamp=timestamp):
+                    with patch("time.time", return_value=timestamp):
+                        with self.assertRaisesRegex(ValueError, "for_time must be"):
+                            totp.now()
+                        with self.assertRaises(ValueError):
+                            totp.verify("invalid")
+                        with self.assertRaises(ValueError):
+                            totp.verify_and_get_timecode("invalid")
+
+    def test_datetimes_outside_range(self):
+        cases = (
+            datetime.datetime.min,
+            datetime.datetime.min.replace(tzinfo=datetime.timezone.utc),
+            datetime.datetime(1969, 12, 31, 23, 59, 59, 999999, tzinfo=datetime.timezone.utc),
+            datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone(datetime.timedelta(hours=1))),
+            datetime.datetime.max.replace(tzinfo=datetime.timezone(datetime.timedelta(hours=-1))),
+        )
+        for for_time in cases:
+            self.assert_time_out_of_range(for_time)
+
+    def test_datetime_range_boundaries(self):
+        totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+        cases = (
+            (datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc), 0),
+            (datetime.datetime(1969, 12, 31, 23, tzinfo=datetime.timezone(datetime.timedelta(hours=-1))), 0),
+            (datetime.datetime.max.replace(tzinfo=datetime.timezone.utc), 8446743359),
+        )
+        for for_time, counter in cases:
+            with self.subTest(for_time=for_time):
+                code = totp.generate_otp(counter)
+                self.assertEqual(totp.timecode(for_time), counter)
+                self.assertEqual(totp.at(for_time), code)
+                self.assertTrue(totp.verify(code, for_time=for_time))
+                self.assertEqual(totp.verify_and_get_timecode(code, for_time=for_time), counter)
+
+    def assert_time_out_of_range(self, for_time):
+        for otp_type in (pyotp.TOTP, pyotp.contrib.Steam):
+            totp = otp_type("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+            calls = (
+                (totp.timecode, (for_time,)),
+                (totp.at, (for_time,)),
+                (totp.verify, ("invalid", for_time)),
+                (totp.verify_and_get_timecode, ("invalid", for_time)),
+            )
+            for method, args in calls:
+                with self.subTest(otp_type=otp_type, method=method.__name__, for_time=for_time):
+                    with self.assertRaisesRegex(ValueError, "for_time must be"):
+                        method(*args)
+
+    def test_verification_normalizes_time_once(self):
+        totp = pyotp.TOTP("GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ")
+        timestamp = 200.5
+        counter = 6
+        code = totp.generate_otp(counter + 2)
+        for verify in (totp.verify, totp.verify_and_get_timecode):
+            for candidate in (code, "invalid"):
+                with self.subTest(method=verify.__name__, candidate=candidate):
+                    with patch.object(totp, "timecode", wraps=totp.timecode) as normalize:
+                        result = verify(candidate, for_time=timestamp, valid_window=2)
+                        normalize.assert_called_once_with(timestamp)
+                    if candidate == code:
+                        self.assertTrue(result)
+                    else:
+                        self.assertIs(result, False)
+
+
 class SteamTOTP(unittest.TestCase):
     def test_match_examples(self):
         steam = pyotp.contrib.Steam("BASE32SECRET3232")
@@ -335,6 +554,15 @@ class ValidWindowTest(unittest.TestCase):
         self.assertFalse(totp.verify("195979", 200, 1))
 
 
+class GetTimeCodeTest(unittest.TestCase):
+    def test_timecode(self):
+        totp = pyotp.TOTP("ABCDEFGH")
+        self.assertEqual(totp.verify_and_get_timecode("451564", 200, 1), 5)
+        self.assertEqual(totp.verify_and_get_timecode("028307", 200, 1), 6)
+        self.assertEqual(totp.verify_and_get_timecode("681610", 200, 1), 7)
+        self.assertFalse(totp.verify_and_get_timecode("195979", 200, 1))
+
+
 class DigestFunctionTest(unittest.TestCase):
     def test_md5(self):
         with self.assertRaises(ValueError) as cm:
@@ -485,7 +713,7 @@ class ParseUriTest(unittest.TestCase):
         self.assertEqual(otp.issuer, "Big Corp")
 
 
-class Timecop(object):
+class Timecop:
     """
     Half-assed clone of timecop.rb, just enough to pass our tests.
     """
@@ -496,15 +724,31 @@ class Timecop(object):
     def __enter__(self):
         self.real_datetime = datetime.datetime
         datetime.datetime = self.frozen_datetime()
+        self.time_patch = patch("time.time", return_value=self.freeze_timestamp)
+        self.time_patch.start()
 
     def __exit__(self, type, value, traceback):
         datetime.datetime = self.real_datetime
+        self.time_patch.stop()
 
     def frozen_datetime(self):
         class FrozenDateTime(datetime.datetime):
             @classmethod
-            def now(cls, **kwargs):
-                return cls.fromtimestamp(timecop.freeze_timestamp)
+            def now(cls, tz=None):
+                instant = timecop.real_datetime.fromtimestamp(timecop.freeze_timestamp, tz)
+                # Construct explicitly: older Python versions can lose fold when
+                # fromtimestamp() is called on a datetime subclass.
+                return cls(
+                    instant.year,
+                    instant.month,
+                    instant.day,
+                    instant.hour,
+                    instant.minute,
+                    instant.second,
+                    instant.microsecond,
+                    tzinfo=instant.tzinfo,
+                    fold=instant.fold,
+                )
 
         timecop = self
         return FrozenDateTime

pyotp-2.10.0/src/pyotp/compat.py

@@ -1,9 +0,0 @@
-import sys
-
-# Use secrets module if available (Python version >= 3.6) per PEP 506
-if sys.version_info >= (3, 6):
-    from secrets import SystemRandom
-else:
-    from random import SystemRandom
-
-random = SystemRandom()

pyotp-2.10.0/src/pyotp/contrib/__init__.py

@@ -1 +0,0 @@
-from .steam import Steam  # noqa:F401

pyotp-2.10.0/src/pyotp/totp.py

@@ -1,118 +0,0 @@
-import calendar
-import datetime
-import hashlib
-import time
-from typing import Any, Optional, Union
-
-from . import utils
-from .otp import OTP
-
-
-class TOTP(OTP):
-    """
-    Handler for time-based OTP counters.
-    """
-
-    def __init__(
-        self,
-        s: str,
-        digits: int = 6,
-        digest: Any = None,
-        name: Optional[str] = None,
-        issuer: Optional[str] = None,
-        interval: int = 30,
-    ) -> None:
-        """
-        :param s: secret in base32 format
-        :param digits: number of integers in the OTP. Some apps expect this to be 6 digits, others support more.
-        :param digest: digest function to use in the HMAC (expected to be SHA1)
-        :param name: account name
-        :param issuer: issuer
-        :param interval: the time interval in seconds for OTP. This defaults to 30.
-        """
-        if digest is None:
-            digest = hashlib.sha1
-        elif digest in [hashlib.md5, hashlib.shake_128]:
-            raise ValueError("selected digest function must generate digest size greater than or equals to 18 bytes")
-
-        self.interval = interval
-        super().__init__(s=s, digits=digits, digest=digest, name=name, issuer=issuer)
-
-    def at(self, for_time: Union[int, datetime.datetime], counter_offset: int = 0) -> str:
-        """
-        Accepts either a Unix timestamp integer or a datetime object.
-
-        To get the time until the next timecode change (seconds until the current OTP expires), use this instead:
-
-        .. code:: python
-
-            totp = pyotp.TOTP(...)
-            time_remaining = totp.interval - datetime.datetime.now().timestamp() % totp.interval
-
-        :param for_time: the time to generate an OTP for
-        :param counter_offset: the amount of ticks to add to the time counter
-        :returns: OTP value
-        """
-        if not isinstance(for_time, datetime.datetime):
-            for_time = datetime.datetime.fromtimestamp(int(for_time))
-        return self.generate_otp(self.timecode(for_time) + counter_offset)
-
-    def now(self) -> str:
-        """
-        Generate the current time OTP
-
-        :returns: OTP value
-        """
-        return self.generate_otp(self.timecode(datetime.datetime.now()))
-
-    def verify(self, otp: str, for_time: Optional[datetime.datetime] = None, valid_window: int = 0) -> bool:
-        """
-        Verifies the OTP passed in against the current time OTP.
-
-        :param otp: the OTP to check against
-        :param for_time: Time to check OTP at (defaults to now)
-        :param valid_window: extends the validity to this many counter ticks before and after the current one
-        :returns: True if verification succeeded, False otherwise
-        """
-        if for_time is None:
-            for_time = datetime.datetime.now()
-
-        if valid_window:
-            for i in range(-valid_window, valid_window + 1):
-                if utils.strings_equal(str(otp), str(self.at(for_time, i))):
-                    return True
-            return False
-
-        return utils.strings_equal(str(otp), str(self.at(for_time)))
-
-    def provisioning_uri(self, name: Optional[str] = None, issuer_name: Optional[str] = None, **kwargs) -> str:
-        """
-        Returns the provisioning URI for the OTP.  This can then be
-        encoded in a QR Code and used to provision an OTP app like
-        Google Authenticator.
-
-        See also:
-            https://github.com/google/google-authenticator/wiki/Key-Uri-Format
-
-        """
-        return utils.build_uri(
-            self.secret,
-            name if name else self.name,
-            issuer=issuer_name if issuer_name else self.issuer,
-            algorithm=self.digest().name,
-            digits=self.digits,
-            period=self.interval,
-            **kwargs,
-        )
-
-    def timecode(self, for_time: datetime.datetime) -> int:
-        """
-        Accepts either a timezone naive (`for_time.tzinfo is None`) or
-        a timezone aware datetime as argument and returns the
-        corresponding counter value (timecode).
-
-        """
-        if for_time.tzinfo:
-            return int(calendar.timegm(for_time.utctimetuple()) / self.interval)
-        else:
-            return int(time.mktime(for_time.timetuple()) / self.interval)