refcount tech notes

These are notes for the package maintainer(s). Most users can ignore them.

History

• Migrated to use poetry 2023-04 after reading https://py-pkgs.org, poetry grated but got over it.
• Jan 2025. poetry 2.0, Significant changes to the pyproject toml.
• installing poetry via pipx.
• BUT had started a branch for packaging with uv. Time to move on anyway.
• Trialing package development using this copier-uvtemplate. Note also the blog post from Simon Wilson on uv

log

# to update to the latest version
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool upgrade copier
cd ~/src/pyrefcount
copier copy --trust "gh:pawamoy/copier-uv" .
direnv allow

Merging some changes manually for some overwritten files:

        modified:   .gitignore
        modified:   CODE_OF_CONDUCT.md
        modified:   CONTRIBUTING.md
        modified:   README.md
        modified:   docs/index.md
        modified:   mkdocs.yml
        modified:   pyproject.toml
        modified:   tests/__init__.py

.envrc:

PATH_add scripts
export PYTHON_VERSIONS="3.12"

make setup

make check-quality

Lots of issues, but mostly e.g. single versus double quotes. In particular launch.json as it has some useful settings for native debugging.

ruff

ruff setup. Back up files under .vscode just in case.

make vscode: "To enable or disable Ruff after changing the enable setting, you must restart VS Code."

uv run ruff check --fix

it fixes only one error compared to 141 reported as fixable by make check-quality.

uv run ruff check --config=config/ruff.toml --fix

Found 367 errors (148 fixed, 219 remaining).
No fixes available (99 hidden fixes can be enabled with the `--unsafe-fixes` option).

Manual syntax changes

`typing.List` is deprecated, use `list` instead Ruff UP035

These are a bit of a bother. Type annotations, I think, encouraged e.g. the use of List instead of list years ago. This grates.

Deploying docs

make docs-deploy requires mkdocs for insiders.

mkdocs gh-deploy:

ERROR   -  Config value 'markdown_extensions': Failed to load extension 'callouts'.
           ModuleNotFoundError: No module named 'callouts'

This was because I had not activated the environment with . ./.venv/bin/activate

mkdocs build
mkdocs gh-deploy

make release version=1.2.7

      raise HTTPError(http_error_msg, response=self)
  requests.exceptions.HTTPError: 400 Client Error: The use of local versions in <Version('1.2.7+d20250114')> is not allowed. See https://packaging.python.org/specifications/core-metadata for more information. for url: https://upload.pypi.org/legacy/

subsequent attempts have an unclear effect, possibly none

✓ Staging files
✗ Committing changes (1)
  > git commit -m "chore: Prepare release 1.2.7"
  On branch testing
  Your branch is up to date with 'origin/testing'.

make release never seems to complete. At best it created some wheels with commit hashs such as refcount-1.2.7.abedeff12456.tar.gz of something like that and pypi refuses to let them be uploaded.

I ended up having to delete tags and doing:

# add and commit
git tag v1.2.7
make build

creates files refcount-1.2.7-py3-none-any.whl refcount-1.2.7.tar.gz which look suitable for upload to pypi.

Yup, ✓ Publishing source and wheel distributions to PyPI

Release steps

• all UT pass
• Merge new features/fixes to devel branch.
• version.py updated
• check readme is up to date

poetry install
poetry version
pytest tests/

Not sure about using poetry for repos push.

poetry config repositories.test-pypi https://upload.pypi.org/legacy/

with .pypirc configured:

rm dist/*
poetry build
ls dist/

twine upload -r testpypi dist/*
# check
twine upload -r pypi dist/*

Code - deprecated

cd ~/src/github_jm/pyrefcount

source ~/anaconda3/bin/activate
my_env_name=testpypirefcount

conda create --name ${my_env_name} python=3.6
conda activate ${my_env_name}
conda install -c conda-forge wheel twine six pytest

conda activate ${my_env_name}
cd ~/src/github_jm/pyrefcount
rm dist/*
python setup.py sdist bdist_wheel
rm dist/*.tar

Importantly to not end up with incorrect display of the readme:

twine check dist/*

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Then and only then:

twine upload dist/*

Documentation

2021-01 Exploring options for putting this on readthedoc. I used in the past sphinx with napoleon extensions to document ela. This was a trial run. Did something more substantial for an internal project (WAA).

Starting afresh with this, reading the RTD guides. Introduces mkdocs. Notice this blog on mkdocs-material which seems like the new cool kid on the block.

Unclear from RTD where to create a new mkdocs project (supposed to be in the root of the python package?) not sure. for now:

cd doc
mkdir mkd
cd mkd/
mkdocs new .

mamba install -c conda-forge mkdocs-material mkdocstrings mamba install -c conda-forge mkdocs-material-extensions

Building the doc:

. ~/config/baseconda
conda activate poetry
mkdocs build --clean --site-dir _build/html --config-file mkdocs.yml
mkdocs serve

testing

# pytest tests/ --cov=refcounts # generates a warning about no coverage data cvollected
coverage run -m pytest
# pytest --cov=refcounts --cov-report html
coverage report
coverage html -d coverage_html

Troubleshooting

OUTDATED no more rst.

pandoc -f markdown -t rst README.md  > README.rst

Can view with the retext program (did not find VScode RST extensions working, or giving out blank output if not, perhaps)

python setup.py check --restructuredtext

Feedback