giterator 0.3.0__tar.gz → 1.0.0__tar.gz

giterator-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: "Continuous Integration"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 1 * * *"
+
+jobs:
+  ci:
+    uses: cjw296/python-workflow/.github/workflows/uv-ci.yml@v2
+    with:
+      package: giterator
+      python-versions: '[ "3.11", "3.14" ]'

giterator-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: "Release"
+
+on:
+  workflow_run:
+    workflows: [Continuous Integration]
+    types: [completed]
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository == 'simplistix/giterator' && github.event.workflow_run.conclusion == 'success' }}
+    outputs:
+      tag: ${{ steps.carthorse.outputs.tag }}
+    steps:
+      - uses: cjw296/python-action/carthorse@v1
+        id: carthorse
+        with:
+          tag-format: 'v{version}'
+          check: "true"
+
+  release:
+    runs-on: ubuntu-latest
+    needs: check
+    if: ${{ needs.check.outputs.tag != '' }}
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Show tag
+        run: echo "${{ toJson(needs.check.outputs) }}"
+        shell: bash
+
+      - name: Download packages from CI run
+        uses: dawidd6/action-download-artifact@v9
+        with:
+          run_id: ${{ github.event.workflow_run.id }}
+          name: Packages
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - uses: cjw296/python-action/carthorse@v1
+        with:
+          tag-format: 'v{version}'

giterator-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+*.egg-info
+.coverage
+.coverage.*
+_build/
+.*cache/
+__pycache__/
+.venv
+.claude
+uv.lock
+README.html

giterator-1.0.0/.python-version

@@ -0,0 +1 @@
+3.11

giterator-1.0.0/.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  commands:
+  - asdf plugin add uv
+  - asdf install uv latest
+  - asdf global uv latest
+  - uv sync --group docs
+  - uv run sphinx-build --fail-on-warning -T -b html docs $READTHEDOCS_OUTPUT/html

giterator-1.0.0/AGENTS.md

@@ -0,0 +1,68 @@
+# Agent Instructions
+
+## Principles
+
+- **Done means green**: a change is only complete when `./happy.sh` exits 0; do not commit until it does.
+- **No unrelated failures**: if `./happy.sh` fails on something unrelated to your changes, do NOT assume it is a pre-existing problem and proceed anyway. Stop immediately and ask the user how to proceed.
+- **Docs for everything public**: new functionality or public API changes must have accompanying docs in `docs/*.rst`
+- **Docs examples must run**: every Python code block and doctest in `docs/*.rst` is executed by pytest via sybil, top to bottom per document in one shared namespace. The root `conftest.py` sandboxes each document (fresh temp cwd, git config isolated), so examples must only touch disk via relative paths or `tmp_path`. Use `.. invisible-code-block: python` for setup that shouldn't render, doctests (`>>>`) to show output or tracebacks, and `run_pytest` from `sybil.testing` to actually execute fixture-style test examples.
+- **No em-dashes or parenthetical asides in prose**: in `docs/*.rst` prose and Python docstrings, never use em-dashes, and never tuck a clause inside parentheses; rephrase with commas or separate sentences. This does not apply to code comments or agent-facing notes such as this file, where both are fine.
+- **No stacked headings in docs**: a heading in `docs/*.rst` must be followed by prose, never immediately by a sub-heading. Add a short lead-in or merge the levels.
+- **Type-annotate public APIs**: all public functions and classes need type annotations; mypy is the gate
+- **Use `compare()` in tests**: assert with `compare(actual, expected=...)`, using `StringComparison` for pattern matches. Bare `assert` only for booleans and `isinstance` (which type-narrows for mypy).
+- **No `pytest.MonkeyPatch`**: use testfixtures instead. `TempDirectory(cwd=True)` replaces `monkeypatch.chdir`; for mocking, prefer `Replacer` methods (`replace.in_environ`, `replace.on_class`, `replace.in_module`), or the `replace_in_environ`/`replace_on_class`/`replace_in_module` context managers for one-offs.
+- **No `noqa`, ever**: this project has zero linter suppressions; don't add them. Fix the underlying issue instead.
+- **No `docs/changes.rst` edits during development**: that file is updated at release time, not as part of feature work.
+
+## Project Overview
+
+Giterator is a Python library and command line tool for doing git things: it wraps
+command-line git to script repository operations and provides helpers for making
+sample repositories in tests.
+
+## Environment
+
+```bash
+uv sync --all-extras --all-groups              # setup or after pulling
+rm -rf .venv && uv sync --all-extras --all-groups  # full reset
+```
+
+## Commands
+
+```bash
+./happy.sh                                     # all checks: required before commit
+uv run pytest                                  # all tests
+uv run pytest tests/test_git.py                # single file
+uv run pytest --cov --cov-report=term-missing  # with coverage
+uv run mypy src tests                          # type checking
+uv run make -C docs html                       # build docs
+uv build                                       # build sdist + wheel
+```
+
+## Architecture
+
+`src/giterator/`: all source. Key modules:
+
+- `git.py`: `Git`, the main class wrapping command-line git; also `User` and `GitError`
+- `testing.py`: `Repo`, for making sample repositories in tests
+- `clock.py`: controllable time source used for commit timestamps
+- `cli.py`: the `giterator` command line entry point
+- `__main__.py`: `python -m giterator` support
+- `typing.py`: type definitions
+
+Config: `pyproject.toml`.
+
+Testing specifics:
+
+- Coverage must be 100% and tracks both `giterator` and `tests`.
+- CLI tests run `python -m giterator` in subprocesses: `tests/conftest.py` sets
+  `COVERAGE_PROCESS_START` and the `coverage-enable-subprocess` dev dependency measures
+  them, so coverage runs in parallel mode.
+- Tests exercise real git via temporary repositories, so a `git` binary is required.
+- Docs examples are collected via the root `conftest.py` (sybil); `testpaths` includes
+  `docs`. Sandboxing is done with pytest fixtures requested via `Sybil(fixtures=...)`:
+  a module-scoped fixture spans exactly one document, and the `sandbox` fixture uses
+  that to chdir into a `TempDirectory(cwd=True)` and point
+  `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM` at controlled files, so examples can never
+  read or write the machine's git config or real filesystem paths. The builtin
+  `tmp_path` is also requested, fresh per example.

giterator-1.0.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

giterator-1.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: giterator
+Version: 1.0.0
+Summary: Python tools for doing git things.
+Project-URL: Homepage, https://github.com/simplistix/giterator
+Project-URL: Documentation, https://giterator.readthedocs.org/en/latest/
+Project-URL: Repository, https://github.com/simplistix/giterator
+Project-URL: Changelog, https://giterator.readthedocs.io/en/latest/changes.html
+Author-email: Chris Withers <chris@withers.org>
+License: MIT
+License-File: LICENSE.rst
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+
+giterator
+=========
+
+|CI|_ |Docs|_
+
+.. |CI| image:: https://github.com/simplistix/giterator/actions/workflows/ci.yml/badge.svg
+.. _CI: https://github.com/simplistix/giterator/actions/workflows/ci.yml
+
+.. |Docs| image:: https://readthedocs.org/projects/giterator/badge/?version=latest
+.. _Docs: http://giterator.readthedocs.org/en/latest/
+
+Python tools for doing git things:
+
+- ``Git`` wraps command-line git for scripting everyday repository operations,
+  with structured access to the log.
+
+- ``read`` and ``write`` replay a repository's history as a series of dated
+  snapshots and turn dated snapshots, such as backups, back into history.
+  The ``giterator`` command line tool packs and unpacks dated files in the
+  same way.
+
+- ``giterator.testing.Repo`` makes sample repositories for automated tests,
+  with machine-independent configuration and single-call commits.
+
+Full documentation is available at http://giterator.readthedocs.org/en/latest/

giterator-1.0.0/README.rst

@@ -0,0 +1,25 @@
+giterator
+=========
+
+|CI|_ |Docs|_
+
+.. |CI| image:: https://github.com/simplistix/giterator/actions/workflows/ci.yml/badge.svg
+.. _CI: https://github.com/simplistix/giterator/actions/workflows/ci.yml
+
+.. |Docs| image:: https://readthedocs.org/projects/giterator/badge/?version=latest
+.. _Docs: http://giterator.readthedocs.org/en/latest/
+
+Python tools for doing git things:
+
+- ``Git`` wraps command-line git for scripting everyday repository operations,
+  with structured access to the log.
+
+- ``read`` and ``write`` replay a repository's history as a series of dated
+  snapshots and turn dated snapshots, such as backups, back into history.
+  The ``giterator`` command line tool packs and unpacks dated files in the
+  same way.
+
+- ``giterator.testing.Repo`` makes sample repositories for automated tests,
+  with machine-independent configuration and single-call commits.
+
+Full documentation is available at http://giterator.readthedocs.org/en/latest/

giterator-1.0.0/conftest.py

@@ -0,0 +1,34 @@
+import os
+from collections.abc import Iterator
+from doctest import ELLIPSIS, REPORT_NDIFF
+
+import pytest
+from sybil import Sybil
+from sybil.parsers.rest import DocTestParser, PythonCodeBlockParser, SkipParser
+from testfixtures import Replacer, TempDirectory
+
+GIT_CONFIG = (
+    b'[user]\n\tname = Giterator\n\temail = giterator@example.com\n[init]\n\tdefaultBranch = main\n'
+)
+
+
+@pytest.fixture(scope='module')
+def sandbox() -> Iterator[None]:
+    # Module scope makes this one sandbox per document: examples create real
+    # repos with relative paths, so each document runs in its own temporary
+    # directory, with git pointed away from the machine's own configuration.
+    with TempDirectory(cwd=True) as tempdir, Replacer() as replace:
+        replace.in_environ('GIT_CONFIG_GLOBAL', tempdir.write('gitconfig', GIT_CONFIG))
+        replace.in_environ('GIT_CONFIG_SYSTEM', os.devnull)
+        yield
+
+
+pytest_collect_file = Sybil(
+    parsers=[
+        DocTestParser(optionflags=REPORT_NDIFF | ELLIPSIS),
+        PythonCodeBlockParser(),
+        SkipParser(),
+    ],
+    pattern='*.rst',
+    fixtures=['sandbox', 'tmp_path'],
+).pytest()

giterator-1.0.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= uv run sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

giterator-1.0.0/docs/api.rst

@@ -0,0 +1,28 @@
+API Reference
+=============
+
+Everything documented here is importable directly from ``giterator``, except
+for :class:`~giterator.testing.Repo`, which lives in ``giterator.testing`` so
+that test-only code is never pulled in by normal use.
+
+giterator
+~~~~~~~~~
+
+.. automodule:: giterator
+    :members:
+    :special-members: __call__
+    :member-order: bysource
+
+.. data:: daily
+    :type: Every
+
+    A daily schedule, for use with :func:`read`.
+
+
+giterator.testing
+~~~~~~~~~~~~~~~~~~
+
+.. automodule:: giterator.testing
+    :members:
+    :member-order: bysource
+    :show-inheritance:

giterator-1.0.0/docs/changes.rst

@@ -0,0 +1,77 @@
+.. py:currentmodule:: giterator
+
+Changes
+=======
+
+1.0.0 (6 Jul 2026)
+------------------
+
+.. warning:: Breaking changes:
+
+  - The ``prefix`` parameter of
+    :meth:`Repo.commit_content <giterator.testing.Repo.commit_content>` has been renamed
+    to ``name`` and is now optional.
+
+- Added :func:`read`, which replays the history of a repository as a series of
+  :class:`Giteration` snapshots, either one per commit or taken on a schedule such as
+  :data:`daily`.
+
+- Added :func:`write`, which turns a series of :class:`Giteration` snapshots into commits,
+  useful for turning dated copies of a project, such as backups, into version history.
+  Combining it with :func:`read` allows a repository's history to be resampled.
+
+- The ``giterator`` command line tool has grown ``pack`` and ``unpack`` commands for
+  moving between files with dates in their names and commits in a repository.
+
+- Added :meth:`Git.log`, which returns the commits in a repository as :class:`Commit`
+  instances, giving structured access to the hash, author, committer, dates and full
+  message of each commit.
+
+- :meth:`Repo.commit_content <giterator.testing.Repo.commit_content>` no longer needs a
+  file name, and the content and commit message can now be given when a test cares
+  about them.
+
+- The documentation has been substantially expanded, and every example in it is now
+  executed as part of the test suite.
+
+- Fixed a bug where :meth:`Git.clone` failed when the source repository was given as a
+  relative path.
+
+- Fixed a bug where calling a :class:`Git` instance with environment variable overrides,
+  as :meth:`Git.commit` does when given explicit dates, ran ``git`` with only those
+  variables rather than the full process environment.
+
+0.4.0 (4 Jul 2026)
+------------------
+
+- Moved to a `uv`__-based, ``pyproject.toml``-driven project layout, with ``main`` replacing
+  ``master`` as the default git branch.
+
+  __ https://docs.astral.sh/uv/
+
+- :meth:`Repo.clone <giterator.testing.Repo.clone>` now always ensures a user is configured in
+  the clone, whether specified explicitly, inherited from the source repo, or falling back to
+  the same default as :meth:`Repo.make <giterator.testing.Repo.make>`, so commits made in
+  clones no longer depend on the git config of the machine the tests are running on.
+
+- :meth:`Git.init` can now pin the name of the initial branch, and
+  :meth:`Repo.make <giterator.testing.Repo.make>` does so by default, using ``main``, so branch
+  names in test repos no longer depend on the git config of the machine the tests are running on.
+
+0.3.0 (4 Feb 2026)
+------------------
+
+- General refresh.
+
+- Add ``short`` parameter to methods that return commit hashes,
+  allowing the full commit hash to be returned.
+
+0.2.0 (1 Oct 2021)
+------------------
+
+- Methods that create commits now return the newly-create commit hash.
+
+0.1.0 (28 Sep 2021)
+-------------------
+
+- Initial release

giterator-1.0.0/docs/conf.py

@@ -0,0 +1,25 @@
+from importlib import metadata
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+}
+
+# General
+source_suffix = '.rst'
+master_doc = 'index'
+project = 'giterator'
+copyright = '2020 onwards Chris Withers'
+version = release = metadata.version(project)
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+autodoc_member_order = 'bysource'
+
+# Options for HTML output
+html_theme = 'furo'
+html_title = 'giterator'
+htmlhelp_basename = project + 'doc'

giterator-1.0.0/docs/development.rst

@@ -0,0 +1,58 @@
+Development
+===========
+
+.. highlight:: bash
+
+The latest development version of the documentation can be found here:
+
+http://giterator.readthedocs.org/en/latest/
+
+If you wish to contribute to this project, then you should fork the
+repository found here:
+
+https://github.com/simplistix/giterator/
+
+Once that has been done and you have a checkout,
+you can follow the instructions below to perform various development tasks.
+
+For detailed development guidelines, code style requirements, and additional commands,
+see ``AGENTS.md`` in the repository root.
+
+Setting up a development environment
+------------------------------------
+
+The recommended way to set up a development environment is to use `uv`__
+to install all groups and extras:
+
+__ https://docs.astral.sh/uv/
+
+.. code-block:: bash
+
+    uv sync --all-extras --all-groups
+
+Running the tests
+-----------------
+
+Once you've set up the environment, the tests can be run from the root of a
+source checkout as follows:
+
+.. code-block:: bash
+
+  uv run pytest
+
+Building the documentation
+--------------------------
+
+The Sphinx documentation is built by doing the following from the
+repository root:
+
+.. code-block:: bash
+
+  uv run make -C docs html
+
+Making a release
+----------------
+
+To make a release, just update the version in ``pyproject.toml``,
+update the change log, and push to https://github.com/simplistix/giterator
+and the GitHub Actions release workflow should take care of the rest.