Align repo with the Java and JS SDKs, and make the lint gate pass

The CI lint job could not pass: flake8 reported ~700 violations (mostly
from the generated package) and mypy 2 errors. Generated code is now
excluded from both, and the real issues in hand-written code are fixed:
18 malformed continuation lines, 6 overlong docstrings, and a
cast(Any, ...) in cardinality.py that was the intent behind the unused
cast import.

Packaging had three sources of version truth: pyproject.toml, setup.py,
and the generator-emitted requirements files, which nothing consumes.
pyproject is now the single manifest, matching the Java pom and the JS
package.json. generate-api.sh appended pytest-asyncio to
test-requirements.txt on every run; both files are now generator-ignored.

- publish.yml runs the test suite before building, 2-space indentation
  like the other workflows, and spells PyPI correctly
- README: the API overview claimed every method accepts response_format;
  analyze operations and determinize() take execution_timeout only. Added
  the async notes after each table, as in the Java README, and fixed a
  typo
- pinned openapi-generator 7.21.0, as in the Java and JS repos
- .gitignore rewritten in the shared layout, with .env and IDE entries

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: alexvbrdn

.flake8

@@ -0,0 +1,10 @@
+[flake8]
+max-line-length = 120
+# E203 (whitespace before ':') conflicts with black's slice formatting.
+extend-ignore = E203
+extend-exclude =
+    regexsolver/_generated,
+    .venv,
+    venv,
+    build,
+    dist

.github/workflows/publish.yml

@@ -1,49 +1,73 @@
-name: Publish to PyPi
+name: Publish to PyPI
 
 on:
-    push:
-      tags:
-        - 'v*'
-  
+  push:
+    tags:
+      - "v*"
+
 jobs:
-    build:
-        name: Build distribution
-        runs-on: ubuntu-latest
-
-        steps:
-        - uses: actions/checkout@v4
-        - name: Set up Python
-          uses: actions/setup-python@v5
-          with:
-            python-version: "3.x"
-        - name: Install pypa/build
-          run: >-
-            python3 -m
-            pip install
-            build
-            --user
-        - name: Build a binary wheel and a source tarball
-          run: python3 -m build
-        - name: Store the distribution packages
-          uses: actions/upload-artifact@v4
-          with:
-            name: python-package-distributions
-            path: dist/
-    publish-to-pypi:
-        name: Publish to PyPI
-        needs:
-        - build
-        runs-on: ubuntu-latest
-        environment:
-            name: pypi
-            url: https://pypi.org/p/regexsolver
-        permissions:
-            id-token: write
-        steps:
-        - name: Download all the dists
-          uses: actions/download-artifact@v4
-          with:
-            name: python-package-distributions
-            path: dist/
-        - name: Publish distribution to PyPI
-          uses: pypa/gh-action-pypi-publish@release/v1
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+
+      - name: Run tests with pytest
+        run: pytest
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/regexsolver
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,66 +1,49 @@
+# Build output
+build/
+dist/
+sdist/
+*.egg-info/
+*.egg
+.eggs/
+develop-eggs/
+.installed.cfg
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
 *$py.class
-
-# C extensions
 *.so
 
-# Distribution / packaging
+# Virtual environments
 .Python
 env/
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
+venv/
+.venv/
 lib/
 lib64/
 parts/
-sdist/
 var/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
+.python-version
 
-# Unit test / coverage reports
-htmlcov/
+# Test / coverage / type checking
+.pytest_cache/
+.mypy_cache/
 .tox/
+.cache
+htmlcov/
 .coverage
 .coverage.*
-.cache
-nosetests.xml
 coverage.xml
-*,cover
+nosetests.xml
 .hypothesis/
-venv/
-.venv/
-.python-version
-.pytest_cache
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
 
-# Sphinx documentation
-docs/_build/
+# Environment
+.env
 
-# PyBuilder
-target/
+# IDE
+.idea/
+.vscode/
+*.iml
 
-# Ipython Notebook
-.ipynb_checkpoints
+# OS
+.DS_Store

.openapi-generator-ignore

@@ -1,6 +1,9 @@
 setup.py
 setup.cfg
 tox.ini
+.gitignore
+requirements.txt
+test-requirements.txt
 git_push.sh
 .travis.yml
 .gitlab-ci.yml
@@ -10,8 +13,7 @@ docs/
 test/
 README.md
 
-
 regexsolver/__init__.py
-regexsolver/client.py
+regexsolver/clients/*
 regexsolver/exceptions.py
 regexsolver/models/*

README.md

@@ -70,7 +70,8 @@ The API can handle terms in two formats:
 - `regex`: a regular expression pattern
 - `fair`: FAIR (Fast Automaton Internal Representation), a stable, signed format used internally by the engine
 
-By default, the engine returns whatever the operation produces, with no extra convertion. Override with `response_format`:
+By default, the engine returns whatever the operation produces, with no extra conversion. Override with `response_format`, accepted by the operations that return a term:
+
 ```python
 from regexsolver import ResponseFormat
 
@@ -109,7 +110,7 @@ Timeout is best effort. The exact time is not guaranteed.
 
 ## API Overview
 
-`RegexSolverClient` and `AsyncRegexSolverClient` exposes the following methods. All methods accept optional keyword arguments `response_format` and `execution_timeout`.
+`RegexSolverClient` and `AsyncRegexSolverClient` expose the following methods. Every method accepts optional keyword arguments: operations that return a term take `response_format`, `deterministic` and `execution_timeout`, while analyze operations and `determinize()` take `execution_timeout` only — the response format is not theirs to choose.
 
 ### Analyze
 
@@ -126,6 +127,8 @@ Timeout is best effort. The exact time is not guaranteed.
 | `client.is_deterministic(term, **kwargs)` | `bool` | `True` if the term's automaton is deterministic. Only a deterministic FAIR guarantees consistent string ordering across paginated `generate_strings()` calls; call `determinize()` first if this is `False`. |
 | `client.subset(term1, term2, **kwargs)` | `bool` | `True` if every string matched by `term1` is also matched by `term2`. |
 
+*Note: For `AsyncRegexSolverClient`, these methods are coroutines and must be awaited.*
+
 ### Compute
 
 | Method | Return | Description |
@@ -138,12 +141,16 @@ Timeout is best effort. The exact time is not guaranteed.
 | `client.repeat(term, min, max, **kwargs)` | `Term` | Computes the repetition of the term between `min` and `max` times. |
 | `client.union(term1, term2, ..., **kwargs)` | `Term` | Computes the union of the given terms. |
 
+*Note: For `AsyncRegexSolverClient`, these methods are coroutines and must be awaited.*
+
 ### Generate
 
 | Method | Return | Description |
 | -------- | ------- | ------- |
 | `client.generate_strings(term, limit, offset, **kwargs)` | `List[str]` | Generates up to `limit` unique strings matched by `term`, skipping the first `offset` strings. |
 
+*Note: For `AsyncRegexSolverClient`, this method is a coroutine and must be awaited.*
+
 ## Cross-Language Support
 
 If you want to use this library with other programming languages, we provide:

generate-api.sh

@@ -11,5 +11,4 @@ openapi-generator-cli generate \
   -o "$OUT_DIR" \
   --additional-properties=packageName="$PACKAGE_NAME",library=asyncio
 
-
-echo "pytest-asyncio >= 1.3.0" >> test-requirements.txt
+echo "API Generation Complete."

openapitools.json

@@ -2,6 +2,6 @@
   "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
   "spaces": 2,
   "generator-cli": {
-    "version": "7.20.0"
+    "version": "7.21.0"
   }
 }

pyproject.toml

@@ -64,6 +64,18 @@ Issues = "https://github.com/RegexSolver/regexsolver-python/issues"
 Documentation = "https://docs.regexsolver.com/"
 "Source Code" = "https://github.com/RegexSolver/regexsolver-python"
 
+[tool.setuptools.packages.find]
+include = ["regexsolver*"]
+
+[tool.mypy]
+exclude = ["regexsolver/_generated/"]
+
+# Generated code is not linted or type checked; it is regenerated from
+# ../m-lab/shared/openapi.yaml by ./generate-api.sh.
+[[tool.mypy.overrides]]
+module = "regexsolver._generated.*"
+follow_imports = "silent"
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"