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

Split from #734, including suggestions from @webknjaz

Co-authored-by: Sviatoslav Sydorenko <wk@sydorenko.org.ua>

.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

.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)

aiomysql/.gitignore

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

aiomysql/__init__.py

@@ -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/_scm_version.pyi

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

aiomysql/_version.py

@@ -0,0 +1,4 @@
+try:
+    from ._scm_version import version
+except ImportError:
+    version = "unknown"

docs/conf.py

@@ -30,25 +30,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
-import re, os.path
-
-def get_release():
-    regexp = re.compile(r"^__version__\W*=\W*'([\d.abrc]+)'")
-    here = os.path.dirname(__file__)
-    root = os.path.dirname(here)
-    init_py = os.path.join(root, 'aiomysql', '__init__.py')
-    with open(init_py) as f:
-        for line in f:
-            match = regexp.match(line)
-            if match is not None:
-                return match.group(1)
-        else:
-            raise RuntimeError('Cannot find version in aiomysql/__init__.py')
-
-
-def get_version(release):
-    parts = release.split('.')
-    return '.'.join(parts[:2])
+from aiomysql import __version__
+
 
 extensions = [
     'sphinx.ext.autodoc',
@@ -82,8 +65,8 @@ def get_version(release):
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-release = get_release()
-version = get_version(release)
+release = __version__
+version = '.'.join(__version__.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

pyproject.toml

@@ -2,5 +2,12 @@
 requires = [
     # Essentials
     "setuptools >= 42",
+
+    # Plugins
+    "setuptools_scm[toml] >= 6.4",
+    "setuptools_scm_git_archive >= 1.1",
 ]
 build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+write_to = "aiomysql/_scm_version.py"