Skip to content

Commit 4f2b467

Browse files
rsgallowayrsgalloway
committed
Merge and resolve conflicts from scaffolding branch
2 parents 00c6fb0 + 040e4da commit 4f2b467

32 files changed

Lines changed: 2550 additions & 1 deletion

‎.editorconfig‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
trim_trailing_whitespace = true
8+
indent_style = space
9+
indent_size = 4
10+
11+
[*.{yml,yaml,toml}]
12+
indent_size = 2
13+
14+
[Makefile]
15+
indent_style = tab

‎.flake8‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[flake8]
2+
max-line-length = 100
3+
max-complexity = 35
4+
exclude = .git,__pycache__,.venv*,venv,build,dist,*.egg-info
5+
extend-ignore = E203,E501,W503
6+
# Enforce documentation for modules, classes, functions, methods, and constructors.
7+
docstring-convention = google

‎.gitattributes‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Normalize text to LF in the repository and on checkout, on every platform.
2+
# Git detects binary files and leaves their contents unchanged.
3+
* text=auto eol=lf

‎.github/workflows/lint.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Lint and type check
2+
3+
on: [push, pull_request]
4+
5+
permissions:
6+
contents: read
7+
8+
jobs:
9+
lint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-python@v5
14+
with:
15+
python-version: '3.12'
16+
- run: python -m pip install --upgrade pip
17+
- run: python -m pip install -e '.[dev]'
18+
- run: make lint typecheck

‎.github/workflows/pages.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Pages
2+
3+
on:
4+
push:
5+
branches: [master]
6+
pull_request:
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
concurrency:
13+
group: pages-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
jobs:
17+
build:
18+
runs-on: ubuntu-latest
19+
timeout-minutes: 10
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.12"
25+
cache: pip
26+
cache-dependency-path: pyproject.toml
27+
- name: Install MkPages
28+
run: python -m pip install '.[docs]'
29+
- name: Generate Jekyll source
30+
run: >-
31+
mkpages build docs --output .mkpages
32+
--url "https://subforkdev.github.io"
33+
--baseurl "/subfork-python"
34+
- name: Build site
35+
uses: actions/jekyll-build-pages@v1
36+
with:
37+
source: ./.mkpages
38+
destination: ./_site
39+
- name: Upload Pages artifact
40+
uses: actions/upload-pages-artifact@v3
41+
with:
42+
path: ./_site
43+
44+
deploy:
45+
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
46+
needs: build
47+
runs-on: ubuntu-latest
48+
permissions:
49+
pages: write
50+
id-token: write
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Configure Pages
56+
uses: actions/configure-pages@v5
57+
- name: Deploy Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4

‎.github/workflows/tests.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Test and package
2+
on: [push, pull_request]
3+
permissions:
4+
contents: read
5+
jobs:
6+
test:
7+
runs-on: ubuntu-latest
8+
strategy:
9+
matrix:
10+
python: ['3.8', '3.10', '3.12', '3.13', '3.14']
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-python@v5
14+
with:
15+
python-version: ${{ matrix.python }}
16+
- run: python -m pip install --upgrade pip
17+
- run: python -m pip install '.[dev]'
18+
- run: python -m pytest
19+
- run: python -m build
20+
- run: python -m twine check dist/*

‎.gitignore‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Python bytecode and compiled extensions
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
7+
# Packaging and build output
8+
build/
9+
dist/
10+
.eggs/
11+
*.egg-info/
12+
*.egg
13+
MANIFEST
14+
15+
# Virtual environments and local credentials
16+
.venv*/
17+
venv*/
18+
.env
19+
.env.*
20+
!.env.example
21+
!.env.*.example
22+
23+
# Test, coverage, type-checker, and linter caches
24+
.pytest_cache/
25+
.mypy_cache/
26+
.ruff_cache/
27+
.tox/
28+
.nox/
29+
.coverage
30+
.coverage.*
31+
htmlcov/
32+
coverage.xml
33+
junit.xml
34+
.hypothesis/
35+
36+
# Local scratch data and notebook checkpoints
37+
/tmp/
38+
/logs/
39+
.ipynb_checkpoints/
40+
41+
# Editor, OS, and agent-local settings
42+
.vscode/
43+
.idea/
44+
*.swp
45+
*.swo
46+
*~
47+
.DS_Store
48+
Thumbs.db
49+
Desktop.ini
50+
.codex/
51+
.agents/
52+
53+
# Generated documentation site
54+
.mkpages/
55+
_site/
56+
.jekyll-cache/

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Contributing
2+
3+
To contribute to this Python client, install its development dependencies using
4+
Python 3.8+ and a modern pip:
5+
6+
```bash
7+
python -m pip install --upgrade pip
8+
python -m pip install -e '.[dev]'
9+
```
10+
11+
## Code quality
12+
13+
Install `.[dev]` to get the pinned development tools. Black 24.8.0, isort 5.13.2,
14+
and Flake8 7.1.1 use 100-column formatting, isort's Black profile, and a Python
15+
3.8 target.
16+
17+
```bash
18+
make format # Sort imports and apply Black to src/ and tests/
19+
make lint # Check formatting, imports, Flake8 and Google-style docstrings
20+
make typecheck # Check annotated library code with mypy
21+
make test # Run the HTTP contract tests
22+
make check # Run lint, type checking and tests
23+
make build # Build distributions and check their metadata
24+
```
25+
26+
Activate your environment first, or specify it explicitly, for example:
27+
`make check PYTHON=.venv/bin/python`. The CI lint job uses the same commands.
28+
EditorConfig defines whitespace and newline conventions for supporting editors.
29+
30+
Add annotations and docstrings to new functions, methods and classes, including
31+
constructors and test helpers. Public docstrings should explain side effects,
32+
permissions, return values and failure behavior where useful. JSON dictionaries
33+
retain `Any` values because node parameters and server response fields are dynamic;
34+
this release does not pretend to provide complete generated response models.
35+
Mypy checks library signatures and bodies; Flake8 and formatting cover both the
36+
library and tests. Runtime tests continue to cover Python 3.8 in CI.
37+
38+
## Versioning
39+
40+
```bash
41+
make version # Show the current version
42+
make check-version # Verify both version fields agree
43+
make bump-patch # 2.0.0 -> 2.0.1
44+
make bump-minor # 2.0.0 -> 2.1.0
45+
make bump-major # 2.0.0 -> 3.0.0
46+
make bump-version VERSION=2.1.0 # Set an explicit stable version
47+
```
48+
49+
Bumps update `pyproject.toml` and `subfork.__version__` together. They do not
50+
commit, tag, or publish. Review and commit the changes before releasing.
51+
52+
## Documentation site
53+
54+
Public documentation lives in `docs/`. Its `mkpages.yml` selects the dark theme.
55+
To generate the Jekyll source with Python 3.12:
56+
57+
```bash
58+
python -m pip install -e '.[docs]'
59+
mkpages build docs --output .mkpages
60+
mkpages preview docs/
61+
```
62+
63+
The Pages workflow builds pull requests and deploys `master`. In repository
64+
**Settings → Pages**, select **GitHub Actions** as the source. The initial site
65+
URL is `https://subforkdev.github.io/subfork-python/`; the workflow supplies its
66+
`--url` and `--baseurl` options. Update those if a custom domain is configured.
67+
Preview serves the documentation at `http://127.0.0.1:4000/`.

‎LICENSE‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2026, Ryan Galloway
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
1. Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
2. Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
3. Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎Makefile‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
PYTHON ?= python
2+
3+
.PHONY: format lint typecheck test check build
4+
format:
5+
$(PYTHON) -m isort src tests scripts
6+
$(PYTHON) -m black src tests scripts
7+
8+
lint:
9+
$(PYTHON) -m black --check src tests scripts
10+
$(PYTHON) -m isort --check-only src tests scripts
11+
$(PYTHON) -m flake8 src tests scripts
12+
13+
typecheck:
14+
$(PYTHON) -m mypy
15+
16+
test:
17+
$(PYTHON) -m pytest
18+
19+
check: lint typecheck test check-version
20+
21+
build: check-version
22+
$(PYTHON) -m build
23+
$(PYTHON) -m twine check dist/*
24+
25+
.PHONY: version check-version bump-patch bump-minor bump-major bump-version
26+
export VERSION
27+
28+
version:
29+
@$(PYTHON) scripts/bump-version.py --show
30+
31+
check-version:
32+
@$(PYTHON) scripts/bump-version.py --check
33+
34+
bump-patch bump-minor bump-major:
35+
@$(PYTHON) scripts/bump-version.py --bump $(@:bump-%=%)
36+
37+
bump-version:
38+
@$(PYTHON) scripts/bump-version.py --set

0 commit comments

Comments
 (0)