giterator 0.3.0__tar.gz → 0.4.0__tar.gz

giterator-0.4.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-0.4.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-0.4.0/.gitignore

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

giterator-0.4.0/.python-version

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

giterator-0.4.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-0.4.0/AGENTS.md

@@ -0,0 +1,59 @@
+# 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`
+- **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 `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.

giterator-0.4.0/CLAUDE.md

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

giterator-0.4.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: giterator
+Version: 0.4.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.

{giterator-0.3.0 → giterator-0.4.0}/README.rst

@@ -1,11 +1,10 @@
-
 giterator
 =========
 
-|CircleCI|_  |Docs|_
+|CI|_ |Docs|_
 
-.. |CircleCI| image:: https://circleci.com/gh/simplistix/giterator/tree/master.svg?style=shield
-.. _CircleCI: https://circleci.com/gh/simplistix/giterator/tree/master
+.. |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/

giterator-0.4.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-0.4.0/docs/changes.rst

@@ -0,0 +1,39 @@
+.. py:currentmodule:: giterator
+
+Changes
+=======
+
+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-0.4.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-0.4.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.

giterator-0.4.0/happy.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -ex
+
+echo "=== Syncing dependencies ==="
+uv sync --all-extras --all-groups
+
+echo "=== Tests + Coverage ==="
+uv run pytest --cov --cov-report=term-missing --cov-fail-under=100
+
+echo "=== Formatting ==="
+uv run ruff format .
+
+echo "=== Type Checking ==="
+uv run mypy src tests
+
+echo "=== Docs Build ==="
+uv run make -C docs clean html SPHINXOPTS=--fail-on-warning
+
+echo "=== All checks passed! ==="

giterator-0.4.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "giterator"
+version = "0.4.0"
+description = "Python tools for doing git things."
+readme = "README.rst"
+authors = [{ name = "Chris Withers", email = "chris@withers.org" }]
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/simplistix/giterator"
+Documentation = "https://giterator.readthedocs.org/en/latest/"
+Repository = "https://github.com/simplistix/giterator"
+Changelog = "https://giterator.readthedocs.io/en/latest/changes.html"
+
+[project.scripts]
+giterator = "giterator.cli:main"
+
+[dependency-groups]
+dev = [
+    "coverage-enable-subprocess>=1.0",
+    "mypy>=1.0",
+    "pytest>=8",
+    "pytest-cov>=6",
+    "ruff>=0.9",
+    "testfixtures>=11",
+]
+docs = [
+    "furo>=2024",
+    "sphinx>=8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/giterator"]
+
+[tool.pytest.ini_options]
+addopts = "-p no:doctest"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.format]
+quote-style = "preserve"
+
+[tool.coverage.run]
+source = ["giterator", "tests"]
+parallel = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "\\.\\.\\.",
+]

{giterator-0.3.0 → giterator-0.4.0/src}/giterator/__main__.py

@@ -1,2 +1,3 @@
 from .cli import main
+
 main()

{giterator-0.3.0 → giterator-0.4.0/src}/giterator/cli.py

@@ -2,11 +2,10 @@ from argparse import ArgumentParser, Namespace
 
 
 class Command:
-
-    def add_args(self, parser: ArgumentParser):
+    def add_args(self, parser: ArgumentParser) -> None:
         pass
 
-    def __call__(self, args: Namespace):
+    def __call__(self, args: Namespace) -> None:
         pass
 
 
@@ -30,6 +29,6 @@ def parse_args() -> Namespace:
     return parser.parse_args()
 
 
-def main():
+def main() -> None:
     args = parse_args()
     args.command(args)

{giterator-0.3.0 → giterator-0.4.0/src}/giterator/clock.py

@@ -7,7 +7,7 @@ class Clock:
     not uniformly.
     """
 
-    def __init__(self):
+    def __init__(self) -> None:
         self._now = datetime(2001, 1, 1, 0).astimezone(timezone.utc)
         self._current_delta = 10
 
@@ -15,3 +15,4 @@ class Clock:
         now = self._now
         self._now = now + timedelta(seconds=self._current_delta)
         self._current_delta += 10
+        return now

{giterator-0.3.0 → giterator-0.4.0/src}/giterator/git.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 from os import makedirs
 from pathlib import Path
 from subprocess import check_output, STDOUT, CalledProcessError
-from typing import Union, Dict, List, Optional
+from typing import Self
 
 from .typing import Date
 
@@ -29,15 +31,17 @@ class Git:
     :param path: The path to an existing work tree or local repo.
     """
 
-    _user: User = None
+    _user: User | None = None
 
-    def __init__(self, path: Union[Path, str]):
+    def __init__(self, path: Path | str):
         if not isinstance(path, Path):
             path = Path(path)
         #: The path where this instance is located.
         self.path: Path = path
 
-    def __call__(self, *command, env: dict = None, cwd: Path = None) -> str:
+    def __call__(
+        self, *command: str, env: dict[str, str] | None = None, cwd: Path | None = None
+    ) -> str:
         """
         Run a git command in this repo. For example:
 
@@ -46,38 +50,56 @@ class Git:
             Git(...)('log', '-1')
         """
         try:
-            output = check_output(
-                ('git',) + command, cwd=cwd or self.path, stderr=STDOUT, env=env
-            )
+            output = check_output(('git',) + command, cwd=cwd or self.path, stderr=STDOUT, env=env)
         except CalledProcessError as e:
             raise GitError(
-                f"{' '.join(e.cmd)!r} gave return code {e.returncode}:\n\n"
-                f"{e.output.decode()}\n\n"
+                f"{' '.join(e.cmd)!r} gave return code {e.returncode}:\n\n{e.output.decode()}\n\n"
             ) from None
         return output.decode()
 
     git = __call__
 
-    def _set_user(self, user: Optional[User]):
+    def _set_user(self, user: User | None) -> None:
         if user:
             self._user = user
             self('config', 'user.name', user.name)
             self('config', 'user.email', user.email)
 
-    def init(self, user: User = None) -> None:
+    def init(self, user: User | None = None, branch: str | None = None) -> None:
         """
         Create an empty Git repository or reinitialize an existing one.
         If the path doesn't exist, it will be created. This includes any missing
         parent directories.
 
         :param user: The user to configure in the local repo.
+        :param branch: The name to use for the initial branch. If not specified,
+            the machine's git default is used.
         """
         makedirs(self.path, exist_ok=True)
-        self('init')
+        command = ['init']
+        if branch:
+            command.extend(['-b', branch])
+        self(*command)
         self._set_user(user)
 
     @classmethod
-    def clone(cls, source: Union[str, Path, 'Git'], path: Union[str, Path], user: User = None):
+    def clone(
+        cls,
+        source: str | Path | Git,
+        path: str | Path,
+        user: User | None = None,
+    ) -> Self:
+        """
+        Clone the ``source`` repo to the ``path`` specified.
+
+        :param source: The repo to clone, either as a path or a :class:`Git` instance.
+        :param path: Where to clone to. Relative paths are resolved relative to the
+            parent of ``source``.
+        :param user: The user to configure in the local clone. If not specified and
+            ``source`` is a :class:`Git` instance, the user from ``source``, if any,
+            is configured. Otherwise, no user is configured and commits in the clone
+            will depend on git's normal identity discovery.
+        """
         if isinstance(source, Git):
             user = user or source._user
             source = source.path
@@ -89,15 +111,15 @@ class Git:
         return git
 
     @staticmethod
-    def _coerce_date(dt):
+    def _coerce_date(dt: Date) -> str:
         return dt if isinstance(dt, str) else dt.isoformat()
 
     def commit(
-            self,
-            msg: str,
-            author_date: Date = None,
-            commit_date: Date = None,
-            short: bool = True,
+        self,
+        msg: str,
+        author_date: Date | None = None,
+        commit_date: Date | None = None,
+        short: bool = True,
     ) -> str:
         """
         Commit changes in this repo, including and new or deleted files.
@@ -111,7 +133,7 @@ class Git:
         command = ['commit', '-m', msg]
         if author_date:
             command.extend(['--date', self._coerce_date(author_date)])
-        env = {}
+        env: dict[str, str] = {}
         if commit_date:
             env['GIT_COMMITTER_DATE'] = self._coerce_date(commit_date)
         self(*command, env=env)
@@ -130,13 +152,13 @@ class Git:
         """
         self('tag', name)
 
-    def tags(self) -> List[str]:
+    def tags(self) -> list[str]:
         """
         Return a list of tags in this repo.
         """
         return self('tag').split()
 
-    def tag_hashes(self) -> Dict[str, str]:
+    def tag_hashes(self) -> dict[str, str]:
         """
         Return a mapping of tag name to commit hash.
         """
@@ -148,13 +170,13 @@ class Git:
         """
         self('checkout', '-b', name)
 
-    def branches(self) -> List[str]:
+    def branches(self) -> list[str]:
         """
         Return a list of branches in this repo.
         """
         return self('for-each-ref', '--format', '%(refname:short)', 'refs/heads/').split()
 
-    def branch_hashes(self) -> Dict[str, str]:
+    def branch_hashes(self) -> dict[str, str]:
         """
         Return a mapping of branch name to commit hash.
         """