build: Convert to poetry (#242)

.github/actions/build-docs/action.yml

@@ -0,0 +1,9 @@
+name: Build Documentation
+description: 'Build Documentation.'
+
+runs:
+  using: composite
+  steps:
+    - name: Build Documentation
+      shell: bash
+      run: make docs

.github/actions/build/action.yml

@@ -0,0 +1,9 @@
+name: Build distribution files
+description: 'Build distribution files'
+
+runs:
+  using: composite
+  steps:
+    - name: Build distribution files
+      shell: bash
+      run: poetry build

.github/actions/publish/action.yml

@@ -11,22 +11,6 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Set up Python 3.11
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.11
-
-    - name: Install dependencies
-      shell: bash
-      run: |
-        pip install -r requirements.txt
-        pip install wheel
-        pip install setuptools
-
-    - name: Building publishable packages
-      shell: bash
-      run: python setup.py sdist bdist_wheel
-
     - name: Publish package distributions to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       if: ${{ inputs.dry_run == 'false' }}

.github/workflows/ci.yml

@@ -39,35 +39,27 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install requirements
-        run: |
-          pipx install virtualenv
-          pip install setuptools
-          pip install -r test-requirements.txt
-          pip install -r test-filesource-optional-requirements.txt
-          pip install -r consul-requirements.txt
-          python setup.py install
-          pip freeze
+      - name: Install poetry
+        run: pipx install poetry
 
-      - name: Run tests
-        run: pytest -s testing -W error::SyntaxWarning
+      - uses: ./.github/actions/build
+      - uses: ./.github/actions/build-docs
 
-      - name: Test packaging
-        run: |
-          sudo rm -rf dist *.egg-info
-          ./test-packaging/test-packaging.sh
+      - name: Run tests
+        run: make test
 
       - name: Verify typehints
         run: make lint
 
-      - name: Verify docs can be successfully built
-        run: make docs
+        #
+        # SDK contract tests
+        #
 
-      - name: Build contract tests
-        run: make build-contract-tests
+      - name: install contract test dependencies
+        run: make install-contract-tests-deps
 
-      - name: Start contract test service
-        run: make start-contract-test-service &
+      - name: start contract test service
+        run: make start-contract-test-service-bg
 
       - name: run contract tests
         run: make run-contract-tests
@@ -123,12 +115,8 @@ jobs:
 
       - name: Install requirements
         run: |
-          pip install setuptools
-          pip install -r test-requirements.txt
-          pip install -r test-filesource-optional-requirements.txt
-          pip install -r consul-requirements.txt
-          python setup.py install
-          pip freeze
+          pipx install poetry
+          poetry install --all-extras
 
       - name: Run tests
-        run: pytest -s testing -W error::SyntaxWarning
+        run: make test

.github/workflows/manual-publish.yml

@@ -17,15 +17,22 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+
+      - name: Install poetry
+        run: pipx install poetry
+
       - uses: launchdarkly/gh-actions/actions/[email protected]
         name: 'Get PyPI token'
         with:
           aws_assume_role: ${{ vars.AWS_ROLE_ARN }}
           ssm_parameter_pairs: '/production/common/releasing/pypi/token = PYPI_AUTH_TOKEN'
 
-      - id: publish
-        name: Publish Package
-        uses: ./.github/actions/publish
+      - uses: ./.github/actions/build
+
+      - uses: ./.github/actions/publish
         with:
           token: ${{env.PYPI_AUTH_TOKEN}}
           dry_run: ${{ inputs.dry_run }}

.github/workflows/release-please.yml

@@ -24,16 +24,29 @@ jobs:
         with:
           fetch-depth: 0 # If you only need the current version keep this.
 
+      - uses: actions/setup-python@v4
+        if: ${{ steps.release.outputs.releases_created }}
+        with:
+          python-version: 3.8
+
+      - name: Install poetry
+        if: ${{ steps.release.outputs.releases_created }}
+        run: pipx install poetry
+
       - uses: launchdarkly/gh-actions/actions/[email protected]
         if: ${{ steps.release.outputs.releases_created }}
         name: 'Get PyPI token'
         with:
           aws_assume_role: ${{ vars.AWS_ROLE_ARN }}
           ssm_parameter_pairs: '/production/common/releasing/pypi/token = PYPI_AUTH_TOKEN'
 
-      - id: publish
-        name: Publish Package
-        uses: ./.github/actions/publish
+      - uses: ./.github/actions/build
+        if: ${{ steps.release.outputs.releases_created }}
+
+      - uses: ./.github/actions/build-docs
+        if: ${{ steps.release.outputs.releases_created }}
+
+      - uses: ./.github/actions/publish
         if: ${{ steps.release.outputs.releases_created }}
         with:
           token: ${{env.PYPI_AUTH_TOKEN}}

.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 .Python
 env/
 build/
+!.github/actions/build/
 develop-eggs/
 dist/
 downloads/
@@ -70,3 +71,6 @@ test-packaging-venv
 
 .vscode/
 .python-version
+
+# Poetry
+poetry.lock

.readthedocs.yml

@@ -3,12 +3,13 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.8"
-
-python:
-  install:
-    - requirements: docs/requirements.txt
-    - requirements: requirements.txt
+    python: "3.10"
+  jobs:
+    post_create_environment:
+      - pip install poetry
+      - poetry config virtualenvs.create false
+    post_install:
+      - poetry install --with docs
 
 sphinx:
   builder: html

CONTRIBUTING.md

@@ -14,22 +14,23 @@ We encourage pull requests and other contributions from the community. Before su
 
 ### Setup
 
-It's advisable to use [`virtualenv`](https://virtualenv.pypa.io/) to create a development environment within the project directory:
+This project is built using [poetry](https://python-poetry.org/). To learn more about the basics of working with this tool, read [Poetry's basic usage guide](https://python-poetry.org/docs/basic-usage/).
+
+To begin development, active the poetry shell and ensure your dependencies are installed.
 
 ```
-mkvirtualenv python-server-sdk
-source ~/.virtualenvs/python-server-sdk/bin/activate
+poetry shell
+poetry install
 ```
 
-To install the runtime and test requirements:
+This library defines several extra dependencies to optionally enhance the SDK's capabilities. Use the following commands to install one or more of the available extras.
 
 ```
-pip install -r requirements.txt
-pip install -r test-requirements.txt
+poetry install --extras "redis consul dynamodb test-filesource"
+poetry install -E redis -E consul -E dynamodb -E test-filesource
+poetry install --all-extras
 ```
 
-The additional requirements files `consul-requirements.txt`, `dynamodb-requirements.txt`, `redis-requirements.txt`, and `test-filesource-optional-requirements.txt` can also be installed if you need to test the corresponding features.
-
 ### Testing
 
 To run all unit tests except for the database integrations:

Makefile

@@ -1,44 +1,72 @@
-
 PYTEST_FLAGS=-W error::SyntaxWarning
 
-test:
-	LD_SKIP_DATABASE_TESTS=1 pytest $(PYTEST_FLAGS)
-
-test-all:
-	pytest $(PYTEST_FLAGS)
-
-lint:
-	mypy --install-types --non-interactive --config-file mypy.ini ldclient testing
-
-docs:
-	cd docs && make html
-
-.PHONY: test test-all lint docs
-
-
 TEMP_TEST_OUTPUT=/tmp/contract-test-service.log
 
-# TEST_HARNESS_PARAMS can be set to add -skip parameters for any contract tests that cannot yet pass
-# TEST_HARNESS_PARAMS := $(TEST_HARNESS_PARAMS) \
-
-
+SPHINXOPTS    = -W --keep-going
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = launchdarkly-server-sdk
+SOURCEDIR     = docs
+BUILDDIR      = $(SOURCEDIR)/build
 # port 8000 is already used in the CI environment because we're running a DynamoDB container
-PORT=10000
-
-build-contract-tests:
-	@cd contract-tests && pip install -r requirements.txt
-
+PORT=9000
+
+.PHONY: help
+help: #! Show this help message
+	@echo 'Usage: make [target] ... '
+	@echo ''
+	@echo 'Targets:'
+	@grep -h -F '#!' $(MAKEFILE_LIST) | grep -v grep | sed 's/:.*#!/:/' | column -t -s":"
+
+.PHONY: install
+install:
+	@poetry install --all-extras
+
+#
+# Quality control checks
+#
+
+.PHONY: test
+test: #! Run unit tests
+test: install
+	@poetry run pytest $(PYTEST_FLAGS)
+
+.PHONY: lint
+lint: #! Run type analysis and linting checks
+lint: install
+	@poetry run mypy ldclient testing
+
+#
+# Documentation generation
+#
+
+.PHONY: docs
+docs: #! Generate sphinx-based documentation
+	@poetry install --with docs
+	@cd docs
+	@poetry run $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+#
+# Contract test service commands
+#
+
+.PHONY: install-contract-tests-deps
+install-contract-tests-deps:
+	poetry install --with contract-tests
+
+.PHONY: start-contract-test-service
 start-contract-test-service:
-	@cd contract-tests && python service.py $(PORT)
+	@cd contract-tests && poetry run python service.py $(PORT)
 
+.PHONY: start-contract-test-service-bg
 start-contract-test-service-bg:
 	@echo "Test service output will be captured in $(TEMP_TEST_OUTPUT)"
 	@make start-contract-test-service >$(TEMP_TEST_OUTPUT) 2>&1 &
 
+.PHONY: run-contract-tests
 run-contract-tests:
-	curl -s https://raw.githubusercontent.com/launchdarkly/sdk-test-harness/v2/downloader/run.sh \
-      | VERSION=v2 PARAMS="-url http://localhost:$(PORT) -debug -stop-service-at-end $(TEST_HARNESS_PARAMS)" sh
-
-contract-tests: build-contract-tests start-contract-test-service-bg run-contract-tests
+	@curl -s https://raw.githubusercontent.com/launchdarkly/sdk-test-harness/v2/downloader/run.sh \
+		| VERSION=v2 PARAMS="-url http://localhost:$(PORT) -debug -stop-service-at-end" sh
 
-.PHONY: build-contract-tests start-contract-test-service run-contract-tests contract-tests
+.PHONY: contract-tests
+contract-tests: #! Run the contract test harness
+contract-tests: install-contract-tests-deps start-contract-test-service-bg run-contract-tests

docs/conf.py

@@ -46,7 +46,6 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx_autodoc_typehints',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
 ]