Use setuptools-scm for versioning (#748)

Use setuptools-scm for versioning

- generate aiomysql/_scm_version.py at build time, fallback to `unknown` if it doesn't exist
- include setuptools-scm-git-archive to support versioning in archives from git tags
- install aiomysql package in readthedocs and access generated version to embed in docs
- fetch git context in workflow to ensure we have all information for setuptools-scm to work
- fetch git context in `make doc`

Split from #734, including suggestions from @webknjaz

Co-authored-by: Sviatoslav Sydorenko <[email protected]>

Author: Nothing4You

.git_archival.txt

@@ -0,0 +1 @@
+ref-names: $Format:%D$

.gitattributes

@@ -0,0 +1,5 @@
+# Force LF line endings for text files
+* text=auto eol=lf
+
+# Needed for setuptools-scm-git-archive
+.git_archival.txt  export-subst

.github/workflows/ci.yml

@@ -58,6 +58,8 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
 
     - name: Setup Python ${{ matrix.py }}
       uses: actions/setup-python@v3

.readthedocs.yaml

@@ -19,5 +19,7 @@ formats:
 - epub
 
 python:
-   install:
-   - requirements: requirements-dev.txt
+  install:
+  - requirements: requirements-dev.txt
+  - method: pip
+    path: .

CHANGES.txt

@@ -24,6 +24,7 @@ To be included in 1.0.0 (unreleased)
 * Required python version is now properly documented in python_requires instead of failing on setup.py execution #731
 * Add rsa extras_require depending on PyMySQL[rsa] #557
 * Migrate to PEP 517 build system #746
+* Self-reported `__version__` now returns version generated by `setuptools-scm` during build, otherwise `'unknown'` #748
 
 
 0.0.22 (2021-11-14)

MANIFEST.in

@@ -44,7 +44,16 @@ start_mysql:
 stop_mysql:
 	docker-compose -f docker-compose.yml stop mysql
 
+# TODO: this depends on aiomysql being installed, e.g. in a venv.
+# TODO: maybe this can be solved better.
 doc:
+	@echo "----------------------------------------------------------------"
+	@echo "Doc builds require installing the aiomysql package in the"
+	@echo "environment. Make sure you've installed your current dev version"
+	@echo "into your environment, e.g. using venv, then run this command in"
+	@echo "the virtual environment."
+	@echo "----------------------------------------------------------------"
+	git fetch --tags --all
 	make -C docs html
 	@echo "open file://`pwd`/docs/_build/html/index.html"
 

Makefile

@@ -0,0 +1 @@
+/_scm_version.py

aiomysql/.gitignore

@@ -32,8 +32,9 @@
 from .connection import Connection, connect
 from .cursors import Cursor, SSCursor, DictCursor, SSDictCursor
 from .pool import create_pool, Pool
+from ._version import version
 
-__version__ = '0.0.22'
+__version__ = version
 
 __all__ = [
 

aiomysql/__init__.py

@@ -0,0 +1,3 @@
+# This stub file is necessary because `_scm_version.py`
+# autogenerated on build and absent on mypy checks time
+version: str