switch to uv from pip and setuptools, switch to new Docker image, update docs, and update models with new Yahoo Fantasy Sports API fields

Author: uberfastman

.github/workflows/python-package.yml

@@ -18,29 +18,27 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+
+    - name: Install uv and set the python version to ${{ matrix.python-version }}
+      uses: astral-sh/setup-uv@v6
       with:
+        version: "0.8.17"
+        enable-cache: true
         python-version: ${{ matrix.python-version }}
+
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        python -m pip install flake8 bandit pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors
-        flake8 . --count --show-source --statistics
-        # exit-zero treats all errors as warnings
-        flake8 . --count --exit-zero --statistics
-    - name: Security lint with bandit
-      run: |
-        # stop the build if there are security warnings
-        bandit -r yfpy/
-#    - name: Test with pytest
-#      run: |
-#        pytest
+        uv sync --locked --all-extras --dev
+
+    - name: Lint with ruff
+      run: make lint
+
+    - name: Security check with bandit
+      run: make secure
+
+#    - name: Run tests with pytest
+#      run: make test_code

.gitignore

@@ -17,13 +17,15 @@ dist/
 
 # Testing
 .pytest_cache/
-test_output/
+output/
 
 # Environment
 *.env*
 !.env.template
-*.venv
+.venv
+.venv*/
 .python-version
+.python-venv
 
 # Credentials
 *private*.json

DEPLOYMENT.md

@@ -3,33 +3,33 @@
 1. *(Optional)* Clear virtual machine of old requirements:
 
     ```shell
-    pip uninstall -y -r <(pip freeze)
+    uv pip uninstall -y -r <(uv pip freeze)
     ```
 
-2. *(Optional)* Check `requirements.txt` and `requirement-dev.txt` for latest dependency versions.
+2. *(Optional)* Check the `dependencies` and `dev-dependencies` sections of `pyproject.toml` for latest dependency versions.
 
 3. *(Optional)* Update virtual machine with the latest dependencies:
 
     ```shell
-    pip install -r requirements.txt -r requirements-dev.txt
+    make update
     ```
 
-4. Lint code with `flake8`:
+4. Lint code with `ruff`:
 
     ```shell
-    flake8 . --count --show-source --statistics
+    make lint
     ```
 
 5. Check code security with `bandit`:
 
     ```shell
-    bandit -r yfpy/
+    make secure
     ```
 
 6. Run *all* `pytest` tests (see following commands for running subsets of tests):
 
     ```shell
-    python -m pytest
+    make test_code
     ```
 
 7. Run *all* `pytest` tests *verbosely*:
@@ -47,19 +47,19 @@
 9. *(Optional)* Run all tests from `pytest` file:
 
    ```shell
-   python -m pytest -v -s -m integration test/integration/test_api_game_data.py
+   python -m pytest -v -s -m integration tests/integration/test_api_game_data.py
    ```
 
 10. *(Optional)* Run *specific* test from `pytest` file:
 
     ```shell
-    python -m pytest -v -s -m integration test/integration/test_api_game_data.py -k test_get_game_key_by_season
+    python -m pytest -v -s -m integration tests/integration/test_api_game_data.py -k test_get_game_key_by_season
     ```
 
 11. *(Optional)* Test Python support using [act](https://github.com/nektos/act) for GitHub Actions:
 
     ```shell
-    act_amd -j build
+    make test_actions
     ```
 
     ***Note***: If `act` is unable to locate Docker, make sure that the required `/var/run/docker.sock` symlink exists. If it does not, you can fix it by running:
@@ -92,7 +92,7 @@
     make docs
     ```
 
-    ***Note***: Running `make test_docs` from the previous step recreates the documentation without building the PyPI package with `setup.py`.
+    ***Note***: Running `make test_docs` from the previous step recreates the documentation without building the PyPI package with `uv`.
 
 16. Create a git commit:
 
@@ -113,7 +113,7 @@
 18. Install `twine` (if not already installed):
 
     ```shell
-    pip install twine
+    uv add twine
     ```
 
 19. *(Optional)* Test deployment by building the PyPI packages, recreating the documentation, and deploying to Test PyPI:

MANIFEST.in

@@ -9,25 +9,58 @@ THIS_FILE := $(lastword $(MAKEFILE_LIST))
 help:
 	@$(DOCS_BUILD) -h $(DOCS_OPTS) $(O)
 
-.PHONY: build verify_build test_docs docs pages test_deploy deploy help Makefile
+.PHONY: update lint secure test_code test_actions test_actions_amd build verify_build get_version pre_build test_docs docs test_deploy uv_test_deploy deploy uv_deploy git_post_deploy git_update_docs help Makefile
 
-build: ## Build PyPI packages for distribution.
-	cd ${HOME}/Projects/personal/yfpy; python setup.py sdist bdist_wheel
+update: ## Update all package dependencies.
+	uv sync --all-extras --dev
+
+lint: ## Lint the package code with ruff.
+	ruff check .
+
+secure: ## Check package code security with bandit.
+	bandit -c pyproject.toml -r .
+
+test_code: ## Run code tests with Pytest.
+	pytest tests
+
+test_actions: ## Test package GitHub Actions using act.
+	act -j build
+
+test_actions_amd: ## Test package GitHub Actions on ARM architecture using act.
+	act --container-architecture linux/amd64 -j build
+
+build: update lint secure test_code ## Build PyPI packages for distribution.
+	rm -rf dist/ && uv build
 
 verify_build: ## Check PyPI packages for issues.
 	twine check dist/*
 
-test_docs: ## Extract YFPY project version from VERSION.py and serve MkDocs documentation locally for testing.
-	export YFPY_VERSION=$$(python -c "from VERSION import __version__; print(__version__)") && mkdocs serve
+get_version: ## Extract Python package version from VERSION.py
+	echo $$(python -c "from VERSION import __version__; print(f'v{__version__}')")
 
-docs: build ## Extract YFPY project version from VERSION.py and build MkDocs documentation for distribution.
-	export YFPY_VERSION=$$(python -c "from VERSION import __version__; print(__version__)") && mkdocs build
+pre_build: ## Set Python package version in VERSION.py using latest git tag, update docs with package version, update Docker Compose files with package and Python versions, and prepare documentation in /docs directory for GitHub Pages.
+	python scripts/pre_build.py
 
-pages: docs ## Prepare documentation in /docs directory for GitHub Pages.
-	python docs-mkdocs/scripts/update_docs_for_github_pages.py
+test_docs: ## Extract Python package version and serve MkDocs documentation locally for testing.
+	export PYTHON_PACKAGE_VERSION=$$(python -c "from VERSION import __version__; print(f'v{__version__}')") && mkdocs serve
 
-test_deploy: pages ## Deploy PyPI packages to Test PyPI.
+docs: pre_build build ## Extract Python package version and build MkDocs documentation for distribution.
+	export PYTHON_PACKAGE_VERSION=$$(python -c "from VERSION import __version__; print(f'v{__version__}')") && mkdocs build
+
+test_deploy: docs verify_build ## Deploy PyPI package to Test PyPI with Twine.
 	twine upload -r testpypi dist/*
 
-deploy: pages ## Deploy PyPI packages to PyPI.
+uv_test_deploy: docs verify_build ## Deploy PyPI package to Test PyPI with uv.
+	export UV_PUBLISH_URL=https://test.pypi.org/legacy/ && export UV_PUBLISH_TOKEN=$$(python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.environ.get('TEST_UV_PUBLISH_TOKEN'))") && uv publish
+
+deploy: docs verify_build ## Deploy PyPI package to PyPI with Twine.
 	twine upload dist/*
+
+uv_deploy: docs verify_build ## Deploy PyPI package to PyPI with uv.
+	export UV_PUBLISH_URL=https://upload.pypi.org/legacy/ && export UV_PUBLISH_TOKEN=$$(python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.environ.get('UV_PUBLISH_TOKEN'))") && uv publish
+
+git_post_deploy:  ## Update git by adding changed files, committing with a message about updating documentation and version number, and pushing
+	git add . && git commit -m 'updated version number and documentation' && git push
+
+git_update_docs:  ## Update git by adding changed documentation files, committing with a message about updating documentation, and pushing
+	git add . && git commit -m 'updated documentation' && git push

Makefile

@@ -1,6 +1,7 @@
 [<img src="https://raw.githubusercontent.com/uberfastman/yfpy/refs/heads/main/docs/yfpy-logo.svg" width="400"/>](https://github.com/uberfastman/yfpy)
 
 ## YFPY - Yahoo Fantasy Sports API Wrapper
+
 Python API wrapper for the Yahoo Fantasy Sports public API
 
 *Author: Wren J. R. (uberfastman)*
@@ -34,9 +35,11 @@ Python API wrapper for the Yahoo Fantasy Sports public API
 <sup>Detailed documentation on YFPY can be found at [https://yfpy.uberfastman.com](https://yfpy.uberfastman.com).</sup>
 
 ### Table of Contents
+
 * [About](#about)
 * [Installation](#installation)
     * [Pip](#pip)
+    * [uv](#uv)
     * [Manual](#manual)
 * [Setup](#setup)
     * [Yahoo Developer Network App](#yahoo-developer-network-app)
@@ -60,6 +63,7 @@ Python API wrapper for the Yahoo Fantasy Sports public API
     * [Development](#development)
 * [Troubleshooting](#troubleshooting)
     * [Yahoo Fantasy Sports API](#yahoo-fantasy-sports-api)
+    * [JetBrains and PyCharm](#jetbrains-and-pycharm)
 
 ---
 
@@ -76,13 +80,23 @@ YFPY is a comprehensive wrapper around the Yahoo Fantasy Sports API. It allows f
 <a name="pip"></a>
 #### Pip
 
-* If you wish to use YFPY within another project, from within your project directory, run
+* If you wish to use YFPY within another project, from within your project directory, run:
     ```shell
     pip install yfpy
     ```
 
     or add `yfpy` to your project `requirements.txt`.
 
+<a name="uv"></a>
+#### uv
+
+* If you wish to use YFPY within another project, from within your project directory, run:
+    ```shell
+    uv add yfpy
+    ```
+    
+    or add `yfpy` to the project `dependencies` section in your `pyproject.toml`.
+
 <a name="manual"></a>
 #### Manual
 
@@ -229,7 +243,7 @@ query.save_access_token_data_to_env_file(
 #### Querying the Yahoo Fantasy Sports API
 
 * See the documentation on the  [`yfpy.query.YahooFantasySportsQuery`](https://yfpy.uberfastman.com/_autosummary/yfpy.query.YahooFantasySportsQuery.html#yfpy.query.YahooFantasySportsQuery) class for example usage of all available queries.
-* See [`quickstart/quickstart.py`](https://github.com/uberfastman/yfpy/blob/main/quickstart/quickstart.py) for example usage output.
+* See [`scripts/quickstart.py`](https://github.com/uberfastman/yfpy/blob/main/scripts/quickstart.py) for example usage output.
   * Uncomment/comment out whichever configuration values in their respective functions with which you wish to experiment.
   * Uncomment/comment out whichever query lines in the `RUN QUERIES` section you wish to run.
   * Uncomment/comment out whichever query lines in the `CHECK FOR MISSING DATA FIELDS` section you wish to check for any new/missing data fields returned by the Yahoo Sports Fantasy Football API.
@@ -250,11 +264,11 @@ YFPY can be used within Docker for a more seamless, platform-agnostic experience
     ```
     Then:
     ```shell
-    python quickstart/quickstart.py
+    python scripts/quickstart.py
     ```
   * Send commands to the running container from your host machine:
     ```shell
-    docker exec -i yfpy-package-1 bash -c "python quickstart/quickstart.py"
+    docker exec -i yfpy-package-1 bash -c "python scripts/quickstart.py"
     ```
 
 <a name="docker-development"></a>
@@ -289,7 +303,7 @@ YFPY has a collection of fully functional code snippets that can be run using [p
 * Before running any integration tests, make a copy of [`auth/.env.template`](https://github.com/uberfastman/yfpy/blob/main/auth/.env.template) in the [`auth/`](https://github.com/uberfastman/yfpy/blob/main/auth/) directory and rename it to `.env`.
 * Copy your Yahoo `Client ID` and `Client Secret` into the environment variables in `.env` so that pytest can use them when hitting the Yahoo Fantasy Sports API.
 * If this is the first time running pytest with your Yahoo API credentials, you ***MUST*** allow interactive prompts within pytest by using the `-s` flag.
-* The fixture values in [`test/integration/conftest.py`](https://github.com/uberfastman/yfpy/blob/main/test/integration/conftest.py) are defined in [`quickstart/quickstart.py`](https://github.com/uberfastman/yfpy/blob/main/quickstart/quickstart.py), and can be changed for testing by uncommenting/commenting out the values inside each respective function.
+* The fixture values in [`test/integration/conftest.py`](https://github.com/uberfastman/yfpy/blob/main/test/integration/conftest.py) are defined in [`scripts/quickstart.py`](https://github.com/uberfastman/yfpy/blob/main/scripts/quickstart.py), and can be changed for testing by uncommenting/commenting out the values inside each respective function.
 
 <a name="run-tests"></a>
 #### Run Tests
@@ -314,12 +328,12 @@ YFPY has only been tested extensively on macOS, but is written to be platform-ag
 <a name="python"></a>
 #### Python
 
-YFPY requires Python 3.10 or later, and has been tested through Python 3.12.
+YFPY requires Python 3.10 or later, and has been tested through Python 3.13.
 
 <a name="development"></a>
 #### Development
 
-Direct project dependencies can be viewed in `requirements.txt`, and additional development and build dependencies (*not* including transitive dependencies) can be viewed in `requirements-dev.txt`.
+Run, development, and build dependencies (*not* including transitive dependencies) can be viewed in `pyproject.toml`.
 
 ---
 
@@ -340,3 +354,8 @@ IndexError: list index out of range
 ```
 
 Typically, when the above error (or a similar error) occurs, it simply means that one of the Yahoo Fantasy Sports API calls failed and so no data was retrieved. This can be fixed by simply re-running data query.
+
+<a name="jetbrains-and-pycharm"></a>
+#### JetBrains and PyCharm
+
+If you are using PyCharm for development against this project and want the IDE to be aware of the installed dependencies in your Python interpreter, PyCharm currently has a bug with its `uv` integration that _requires_ the project to have the `uv` Python interpreter exists in a `.venv` directory in the project root. In the event that you have a `uv` Python interpreter configured elsewhere, you can run `ln -sf /path/to/uv/interpreter/directory .venv` in the YFPY project root, and then configure the Python interpreter in PyCharm to point to the Python executable in the `.venv` symbolic link, and all of your installed dependencies will show up and the IDE will be aware that they are installed.

README.md

@@ -1,2 +1,2 @@
 # DO NOT EDIT - VERSIONING CONTROLLED BY GIT TAGS
-__version__ = "v16.0.3"
+__version__ = "16.0.3"

VERSION.py

@@ -1,5 +1,5 @@
 # minimum supported Python version
-__version_minimum_python__ = "3.10"
+__version_minimum_python__ = "3.10.0"
 
 # minimum supported Python version
-__version_maximum_python__ = "3.12"
+__version_maximum_python__ = "3.13.7"

VERSION_PYTHON.py

@@ -1,11 +1,11 @@
 services:
   package:
     build:
-      # DO NOT EDIT PYTHON VERSION BUILD ARGUMENTS - VERSIONING CONTROLLED BY GIT TAGS
+      # DO NOT EDIT PYTHON VERSION BUILD ARGUMENTS - VERSIONING CONTROLLED BY BUILD PROCESS
       args:
       - PYTHON_VERSION_MAJOR=3
-      - PYTHON_VERSION_MINOR=12
-      - PYTHON_VERSION_PATCH=0
+      - PYTHON_VERSION_MINOR=13
+      - PYTHON_VERSION_PATCH=7
       - BUILD_PLATFORM=linux/amd64
       context: .
       dockerfile: docker/Dockerfile