fiscalclock for Python
Python package for fiscalclock, a fiscal calendar engine. You describe a fiscal calendar as a JSON definition, and the package answers questions about it: which fiscal year, quarter, period and week a date falls in, the bounds of any period, labels such as Q4 FY2023, and a day-by-day date dimension.
The package has no built-in calendars. Every calendar is a definition you supply, in the format specified in spec/definition-v1.md.
All computation happens in the fiscalclock Rust core, compiled into this package. The Python layer only converts values, so results are identical to the Rust crate and the npm package.
Status: 0.1.0 is the first release. The definition format and API are version 1 drafts and may change before 1.0.
Install
pip install fiscalclock
Wheels are published for CPython 3.10 and later (one stable-ABI wheel per platform) and for free-threaded CPython 3.14.
Example
A 4-5-4 calendar whose year ends on the Saturday nearest 31 January:
import datetime as dt
from fiscalclock import FiscalCalendar
cal = FiscalCalendar({
"spec_version": 1,
"year": {"type": "week_based",
"anchor": {"edge": "end", "month": 1, "day": "last", "rule": "nearest"}},
"week": {"starts_on": "sunday", "numbering": "contains_start"},
"subdivision": {"type": "week_pattern", "periods": [4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5, 4],
"quarters": [3, 3, 3, 3], "extra_week": {"period": 12}},
"naming": {"default": "fy", "schemes": {"fy": {"year_number": "start",
"templates": {"year": "FY{yyyy}", "quarter": "Q{q} FY{yyyy}"}}}},
})
fy2023 = cal.period("year", 2023)
assert fy2023.start == dt.date(2023, 1, 29)
assert fy2023.last_day == dt.date(2024, 2, 3)
assert fy2023.weeks == 53
here = cal.locate(dt.date(2024, 2, 3))
assert cal.format(here.quarter) == "Q4 FY2023"
assert cal.parse("Q4 FY2023") == here.quarter
API
FiscalCalendar(definition) takes a JSON string or a mapping and raises FiscalclockError if the definition is invalid. Its methods are locate, period, shift, parent, children, years, format, parse, dimension, dimension_csv and explain, as described in spec/api-v1.md.
PeriodandLocationare frozen dataclasses withdatetime.datefields. Every period is the half-open interval[start, end_exclusive), andlast_dayis the day beforeend_exclusive.dimensionreturns a list of dicts with dates as ISO strings, ready for a data frame.call_json(op, args)and the module-levelcall_jsonandvalidate_jsontake and return JSON text exactly as the core produces it.validate(definition)returns the validation result as a dict and does not raise.FiscalclockErroris aValueErrorwith the stablecode, the JSONpath,message,hintanddetailsof the first error, anderrorsholding all of them.
Dates
Date arguments accept only an object whose type is exactly datetime.date, or an ISO YYYY-MM-DD string. A datetime.datetime, including a pandas Timestamp, raises FiscalclockError with code TIMESTAMP_REJECTED, because the calendar day of a timestamp depends on the time zone. Convert it to a date in the time zone you mean first.
How the results are checked
- 112 shared conformance vector files (4,070 cases) are run by the Rust, Python and npm test suites. Expected results come from cited sources or from independent generators, never from fiscalclock itself. See
conformance/. - Week-based years are checked against Python's
date.isocalendar()for every year from 1600 to 2399, and a slow day-by-day reference implementation is compared with the core for every date from 1900 to 2200. - Property tests check that periods tile and nest, and that
shiftandformat/parseround-trip. - On every push, CI runs all vectors through Rust and through the Python and npm packages on Linux, macOS and Windows and requires the outputs to match byte for byte.
Supply chain
This package is built and published by the release workflow from a version tag on main, after a smoke test of the built packages on Linux, macOS and Windows and the maintainer's approval. Every release file has a build provenance attestation. To check a wheel or sdist downloaded from PyPI or the GitHub release:
gh attestation verify <file> --repo Karthik-beta/fiscalclock
Report vulnerabilities privately as described in SECURITY.md. Changes are listed in the changelog.
Licence
Licensed under either of Apache License, Version 2.0 or MIT licence, at your option.
1 maintainer
Metadata
1 maintainer
Release files for fiscalclock 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fiscalclock-0.1.0.tar.gz | 61.1 kB | With provenance | Details for fiscalclock-0.1.0.tar.gz |
Built distributions (wheels)
Total release size: 6.6 MB
Release files / fiscalclock-0.1.0.tar.gz
| Download URL | fiscalclock-0.1.0.tar.gz |
|---|---|
| Size | 61.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0d9a379c0180506e4414eeb9a5b4b7f8a231dd2e8bd49522d98b117ef76b17ee
|
|
BLAKE2b-256 checksum How to use checksums |
475b6b6e5a0db6a885c4d6b439c5addb4c157d3038fad278366c545c96ad8a61
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-win_amd64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-win_amd64.whl |
|---|---|
| Size | 296.5 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading Windows x86-64 |
|
SHA-256 checksum How to use checksums |
19e0b487e8aae6356b3cb7fb5008bd4aac28510943a98d900bd9596f9119a2fb
|
|
BLAKE2b-256 checksum How to use checksums |
6f79640eb4df71971cb20130f0fe1a26c8e42a15be4e0cf6f782f7e8aff01aaf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 654.5 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
57796e6627b937aef93c630434bcdc6a6ea12a5180d26eaf59e666af36c7fbe6
|
|
BLAKE2b-256 checksum How to use checksums |
240b83612ba5b1b7105b5fddbdcf303f4883bd2cf34dafcbb13a8d599f940419
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-musllinux_1_2_aarch64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 617.6 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
ea8f186a080ab0773a4b925b7a741a79308ce1e25de09aac8fdd15d1f84121a4
|
|
BLAKE2b-256 checksum How to use checksums |
8735f382bb00a7f157326ec0e8af5d7f634a42a8523ddcfc338e9660b5cafb33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-manylinux_2_28_x86_64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 449.5 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
e333aacb97a175a9cec0a0ea7699985a92e43f9525405f3b6fee11186505da5c
|
|
BLAKE2b-256 checksum How to use checksums |
a5071a476a3966cdf4f5624cbf38a5db3da84b3a5faa2cbb3b71eb60814118bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-manylinux_2_28_aarch64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 440.5 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
a77f17c9d7d5a5f94eae8487dd77ac337530780fb59876c80fda458cd7fbd463
|
|
BLAKE2b-256 checksum How to use checksums |
50d666280bea4712d91688f20f9be94833cb5f291c3541e6a5e71c0306c48976
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-macosx_11_0_arm64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-macosx_11_0_arm64.whl |
|---|---|
| Size | 398.8 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e82e35c79df3094a4e3a1e902636dc9ae60b24f94bdccf1f0f420e16f6f8cb53
|
|
BLAKE2b-256 checksum How to use checksums |
eedcfee6513ce271c8622abc45325e234d2ac970b5fb792c226b03cc9a307112
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp314-cp314t-macosx_10_12_x86_64.whl
| Download URL | fiscalclock-0.1.0-cp314-cp314t-macosx_10_12_x86_64.whl |
|---|---|
| Size | 407.1 kB |
| Tags | CPython 3.14 CPython 3.14 free-threading macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
8e84a102d498a42980b8759792d5ac9d0f43d64d6890624fb3dac8b97856ad01
|
|
BLAKE2b-256 checksum How to use checksums |
029ce2601cc9508649f9bc73d104a82beab734317331768e81027ac63c677b18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-win_amd64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 301.9 kB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e0d4ee3c0ba9d708a32248579b98361608b6d1f9c9d697d921f59d590eff99a8
|
|
BLAKE2b-256 checksum How to use checksums |
23bac20b832b8bf59f0ddaeb5fa5b5318ed7e1cec95e4b93447cde0e5a284f3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 659.1 kB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
54b5544efdac638879a765ad452a06de316d995faef5ce7673ea28a605deaa6b
|
|
BLAKE2b-256 checksum How to use checksums |
ef8e287d827865683e792f99c62edeab1a4593c9d27686bd30c8f5a7b2ad51d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 623.0 kB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
1e106178c2593d03783f2fb4fc6541f6fbc1a3f203d0b3811b1012c01087a88c
|
|
BLAKE2b-256 checksum How to use checksums |
6111dd4c9aaa8eb0323a09cc63dc26cebf2d9db123a19182f00ca848e3d26a21
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 456.2 kB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
6322de277496cc2c0d1c2aa72232ea8a088bcce3248b851990fa4acd57cd204a
|
|
BLAKE2b-256 checksum How to use checksums |
7b653ace0f8b7bffd7b66ed315cae53c75c6bb450da9e8b60632196aa84422cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 445.5 kB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
503d315704cd37629e5aa10e1fef1668285a99bec94da46318a6f10219f5df1c
|
|
BLAKE2b-256 checksum How to use checksums |
d99512fe8420bcf58d5c91c6c16f43d4fa51ea552189ecc5372e3e3995c9e35f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 403.9 kB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
8c2e85ea7abde1b3916142971caf468950bfbcc78e0ad6f9183cfd7364018fc2
|
|
BLAKE2b-256 checksum How to use checksums |
32df39944b2104c01eb79f873ae6793dc63ba1aaecced553f59d7ea4b3169373
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fiscalclock-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | fiscalclock-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 409.7 kB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
6aa5c52612ebf2a75b3d9b47627f49c010e5887906b47bfb8cc80e1c927cc5d1
|
|
BLAKE2b-256 checksum How to use checksums |
4d8794b9abd3c5dfcf0bb7210cfb163fbdab483b98f140fa42a3ccbbca8f4903
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for fiscalclock 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 15 files in this release have been uploaded with provenance metadata.
Attestation for fiscalclock-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
