datethyme

TODO:

• add add_hours_strict (fail if wrap) and add_hours_maybe (return None if wrap)
• add minutes|seconds_elapsed and minutes|seconds_remaining properties?

Running this project requires copier, git, uv, and flake. Install nix and install the others by running nix-shell -p uv python3 git. You can now copy the project and run the toy CLI provided out-of-the-box:

copier copy --trust \
    /home/isaac/repos/dev-envs/python-uv-nix /tmp/hello-world \
    --data-file /home/isaac/repos/dev-envs/python-uv-nix/example-data-uv.yml

nix run /tmp/hello-world

You can also enter a development environment with all dependencies installed:

nix develop

Once in this dev shell, you have a number of development utils you can try out (via just):

✔just
✔just format
✔just check
✔just fix
✔just typecheck
✔just lint
✔just deal
✔just vulture
✔just pydeps-full
✔just pydeps
✔just pydeps-simple
✔just view-deps
✔just snakefood
✔just deply
✔just bandit
✔just bandit-html
✔just bandit-view
✔just pyflame
✔just flamegraph
✔just perf-flamegraph
✔just check-structure
✔just check-imports
✔just smoke
✔just unit
✔just test
✔just test-cov
☐ just docs
✔just scalene
✔just view-cov
☐ just view-docs
✔just view-flamegraphs
✔just sbom

lefthook validate
lefthook run all

Roadmap

Add FilteredRange types (separate because they will behave differently)

Modify check_structure script to add inherited methods to subclasses (especially important for abstract classes)

deal tests

hypothesis tests

0. ✔ Sync package lists in uv.nix.jinja and README.md

1. ✔ Parametrize each package for copier and update copier.yml

2. ✔ Clean up copier.yml and example-data.yml

3. ✔ Get impure environment working -> draw from buildFHSUserEnv approach in consilium and other projects

4. ✔ Write working version of scripts and test them on datethyme

5. ✔ create reference project (revised from datethyme)

6. ✔ use copier to re-create it (make a datethyme answers file)

7. ✔ find good CLI tools for diffing an entire folder

8. ✔ iteratively modify template until copier perfectly re-creates the reference project

9. ✔ package mdformat with mdformat-mkdocs (via nix)

10. ✔ remove super-linter, but look over it and steal any good ideas

11. ✔ add commitizen and commitmsgfmt ✔

12. ✔ Modify nix to support any python version via nixpkgs-python and tox

13. ✔ Read through jinja2-ansible-filters

14. Go through https://www.youtube.com/results?search_query=nix+and+python and any relevant NixCon talks

15. ✔ restructure nix code

16. ✔ add poetry support (selectable via copier)

17. re-make datethyme package using template, iteratively polishing the template

18. add copier switch to include a CLI or not

Later

Note: first get working the way it is for datathyme.

0. conventional-changelog

1. Package all docs packages via nix, since they run independently of the other Python packages.

2. Do the same for testing dependencies, if possible.

3. Add different types of git hooks

• Client-Side Hooks

  • Pre-commit hooks run before a commit is created and are ideal for code quality checks. They're perfect for running linters, formatters, static analysis tools, or tests to catch issues before they enter the repository. If the hook exits with a non-zero status, the commit is aborted

  • Prepare-commit-msg hooks execute after the default commit message is created but before the editor opens. These work well for automatically adding ticket numbers, branch names, or standardized formatting to commit messages based on branch patterns or other context

  • Commit-msg hooks run after you've written your commit message and are excellent for enforcing commit message conventions. They can validate that messages follow specific formats, contain required information like issue references, or meet length requirements

  • Post-commit hooks trigger after a commit completes successfully. Since they can't affect the commit outcome, they're useful for notifications, triggering builds, updating external systems, or logging commit information

  • Pre-rebase hooks run before rebasing and help prevent rebasing published commits or branches that shouldn't be rebased. They're particularly valuable for protecting main branches or enforcing workflow policies

  • Post-checkout and post-merge hooks execute after checking out branches or completing merges. These are ideal for environment setup tasks like updating dependencies, clearing caches, generating files, or syncing external resources that depend on the current branch state

• Server-Side Hooks

  • Pre-receive hooks run before any references are updated when receiving a push. They're powerful for enforcing repository-wide policies like preventing force pushes to protected branches, validating that all commits meet standards, or checking permissions before allowing updates

  • Update hooks execute once per branch being updated and are perfect for branch-specific policies. They can enforce different rules for different branches, validate individual commits, or check that updates follow branching strategies

  • Post-receive hooks run after all references are successfully updated and are ideal for deployment triggers, sending notifications, updating issue trackers, or kicking off CI/CD pipelines. Since they run after the push succeeds, they're commonly used for automation that depends on the repository being in its new state

Dependency Classes

Dependency Classes

TODO: look at jj-fzf, lazyjj, gg-jj look at luxuries

• dependency resolution (should already be installed)

  • uv ✔

• miscellaneous (semver via Python)

  • semver ✔

• task running / hooks (installable via Python or Nix; Nix preferred)

  • just ✔
  • lefthook ✔

• interactive programming (installable via Python or Nix; Nix preferred)

  • ipython ✔

• static type checking (installable via Python or Nix; Nix preferred)

  • mypy ✔
  • ty ✔

• source code visualization (graphviz and pydeps via Nix, the rest via Python)

  • pydeps ✔
  • graphviz ✔
  • deply ✔
  • snakefood3 ✔
  • grimp ✔

• performance profiling (flamegraph and scalene via Nix, pyflame via Python)

  • pyflame ✔
  • scalene ✔
  • flamegraph-rs (cargo-flamegraph in nix) ✔

• software supply chain, security (installable via Python, but Nix preferred)

  • cyclonedx-python ✔
  • bandit ✔

• testing (installed via Python for now)

  • pytest ✔
  • pytest plugins: --> look at these
    • mock ✔
    • testmon ✔
    • cov ✔
    • loguru ✔
    • profiling video ✔
  • coverage ✔
  • hypothesis ✔
  • tox ✔

• docs (installed via Python for now)

  • mkdocs ✔
  • mkdocstrings ✔
  • mkdocstrings-python ✔
  • mkdocs-material ✔
  • pygments ✔

• formatters / linters

  • installable via Python or Nix:
    • ruff ✔
    • mdformat + mdformat-mkdocs TODO
    • yamlfmt OR yamllint ✔
    • pyprojectsort
    • toml-sort ✔
  • installable only via Nix or other package manager:
    • treefmt + treefmt-nix ✔
    • alejandra ✔
    • super-linter TODO
    • markdown-code-runner OR mdsf ✔
    • markdownlint-cli2 OR markdownlint-cli TODO
    • just-formatter ✔

To Look at for Later

• pystackflame

datethyme

A savory approach to date and time, built on Pydantic and datetime, with an emphasis on input validation and date/time arithmetic.

Roadmap

• review which dunder methods to use for what - init - repr - str - bool - eq - ne - hash - lt - gt - le - ge - - int - float - bytes - complex - format - enter - exit - - add + : - sub - : - mul * : - truediv / : - mod % : - floordiv // : - pow: ** : range creation - matmul @ : - - radd - rsub - rmul - rtruediv - rmod - rfloordiv - rpow - rmatmul - - and: composite from elementary - or | : composite span creation? - xor ^ : inverse composite span (complement) creation? - rshift >> : span creation - lshift << : reverse span creation? - rand
  - ror - rxor - rrshift - rlshift - - neg - pos - invert - - iadd - isub - imul - itruediv /= : - imod %= : - ifloordiv //= : - ipow **= : - imatmul @= : - iand &= : - ior |= : - ixor ^= : - irshift >>= : - ilshift <<= : - - divmod - rdivmod - abs - index - round - trunc - floor - ceil - - getattr - getattribute - setattr - delattr - dir - - prepare - instancecheck - subclasscheck - init_subclass - subclasses - mro_entries - class_getitem - - set_name - get - set - delete - - buffer - release_buffer - - new - del - - aenter - aexit - aiter - anext - await - -

• add round_hour(), round_minute(), etc.

• add support for conditional ranges (and maybe spans), for example DateRange(..., filter=lambda wd: wd < 6)

• add support for composite spans and ranges (union as opposed to hull)

• localization: add DateStrings class with defaults for popular languages and possibility to pass custom strings -> DateStrings.lookup("mon", 4), DateStrings.get_with_fallback(), DateStrings.format(date: Date)

• add stdlib and tuple and namedtuple and dict properties?

• add iter() and items()?

• add add_hours, add_minutes, add_seconds to Time

• add TimeDelta object?

• rename span to interval

• remove DateRange in favor of DateRange: 'range' for discrete sequences, 'span' (or 'interval'?) for uncountable intervals

• rewrite using class Time(_Time), etc. to avoid mypy 'method-assign' error -> get rid of _interactions.py (use inheritance instead of monkey-patching; measure performance)

• [ ]

Type Interactions

**

---------------------------------------------------------
|          |    Date      |     Time     |   DateTime   |
|----------|--------------|--------------|--------------|
| Date     | DateRange    |      ND      | DateTimeSpan |
| Time     |     ND       |   TimeSpan   |      ND      |
| DateTime | DateTimeSpan | DateTimeSpan | DateTimeSpan |
---------------------------------------------------------

&

---------------------------------------------------------
|          |    Date      |     Time     |   DateTime   |
|----------|--------------|--------------|--------------|
| Date     |      ND      |   DateTime   |      ND      |
| Time     |   DateTime   |      ND      |      ND      |
| DateTime |      ND      |      ND      |      ND      |
---------------------------------------------------------

--------------------------------------------------------------
|               |   DateRange  |    TimeSpan  | DateTimeSpan |
|---------------|--------------|--------------|--------------|
| DateRange     |   DateRange  |      ND      |      ND      |
| TimeSpan      |      ND      |    TimeSpan  |      ND      |
| DateTimeSpan  |      ND      |      ND      | DateTimeSpan |
--------------------------------------------------------------

Date ** Date -> DateRange Time ** Time -> TimeSpan DateTime ** DateTime -> DateTimeSpan

Date ** Time -> ND

---

Create sister package thymeline