diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index e56abb63..e2de4eca 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -16,19 +16,20 @@ jobs: strategy: fail-fast: false matrix: - python-version: ["3.9", "3.10", "3.11"] + python-version: ["3.9", "3.10", "3.11", "3.12"] steps: - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v3 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - name: Install dependencies run: | python -m pip install --upgrade pip - python -m pip install flake8 pytest + python -m pip install flake8 if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + if [ -f test-requirements.txt ]; then pip install -r test-requirements.txt; fi - name: Lint with flake8 run: | # stop the build if there are Python syntax errors or undefined names @@ -37,4 +38,21 @@ jobs: flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - name: Test with pytest run: | - pytest + pytest --cov=cfbd --cov-report=term --cov-report=xml + - name: Upload coverage reports + uses: codecov/codecov-action@v4 + if: matrix.python-version == '3.12' + continue-on-error: true + with: + file: ./coverage.xml + flags: unittests + name: codecov-umbrella + - name: Build package + if: matrix.python-version == '3.12' + run: | + python -m pip install wheel + python setup.py sdist bdist_wheel + - name: Verify package can be imported + if: matrix.python-version == '3.12' + run: | + python -c "import cfbd; print('āœ“ Package imported successfully')" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..d8240d49 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,128 @@ +# Contributing to cfbd-python + +Thank you for your interest in contributing to cfbd-python! This document provides guidelines and instructions for contributing. + +## Development Setup + +1. **Clone the repository** + ```bash + git clone https://github.com/CFBD/cfbd-python.git + cd cfbd-python + ``` + +2. **Create a virtual environment** + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` + +3. **Install dependencies** + ```bash + pip install -r requirements.txt + pip install -r test-requirements.txt + ``` + +4. **Install the package in development mode** + ```bash + pip install -e . + ``` + +## Running Tests + +Run the full test suite: +```bash +pytest --cov=cfbd +``` + +Run specific test files: +```bash +pytest test/test_games_api.py +``` + +Run with verbose output: +```bash +pytest -v +``` + +## Code Quality + +### Linting + +This project uses flake8 for linting. Run linting checks with: + +```bash +# Check for syntax errors and undefined names +flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + +# Check for style issues (warnings only) +flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics +``` + +### Code Style + +- Follow PEP 8 guidelines +- Maximum line length: 127 characters +- Use meaningful variable and function names +- Add docstrings to public functions and classes + +## Building the Package + +To build the package locally: + +```bash +pip install build +python -m build +``` + +This creates distribution files in the `dist/` directory. + +## Submitting Changes + +1. **Fork the repository** on GitHub + +2. **Create a new branch** for your changes + ```bash + git checkout -b feature/your-feature-name + ``` + +3. **Make your changes** and commit them + ```bash + git add . + git commit -m "Description of your changes" + ``` + +4. **Run tests and linting** to ensure everything works + ```bash + pytest --cov=cfbd + flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + ``` + +5. **Push your changes** to your fork + ```bash + git push origin feature/your-feature-name + ``` + +6. **Open a Pull Request** on GitHub + +## Pull Request Guidelines + +- Include a clear description of the changes +- Reference any related issues +- Ensure all tests pass +- Maintain or improve code coverage +- Follow the existing code style + +## Getting Help + +If you have questions or need help: +- Open an issue on GitHub +- Check the [README](README.md) for basic information +- Review existing issues and pull requests + +## Code of Conduct + +Please be respectful and constructive in all interactions with the project and community. + +## License + +By contributing to cfbd-python, you agree that your contributions will be licensed under the MIT License. diff --git a/README.md b/README.md index f0583588..58c3b8ea 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,11 @@ with cfbd.ApiClient(configuration) as api_client: ``` +### Examples + +See the `examples/` directory for more usage examples: +- `examples/basic_usage.py` - Basic API usage demonstration + ## Documentation for API Endpoints All URIs are relative to *https://api.collegefootballdata.com* diff --git a/cfbd/models/division_classification.py b/cfbd/models/division_classification.py index 644381fc..57162eec 100644 --- a/cfbd/models/division_classification.py +++ b/cfbd/models/division_classification.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/cfbd/models/game_status.py b/cfbd/models/game_status.py index 97c40129..967604d1 100644 --- a/cfbd/models/game_status.py +++ b/cfbd/models/game_status.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/cfbd/models/media_type.py b/cfbd/models/media_type.py index c36122b2..ded2d9ae 100644 --- a/cfbd/models/media_type.py +++ b/cfbd/models/media_type.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/cfbd/models/recruit_classification.py b/cfbd/models/recruit_classification.py index e3111978..f666df35 100644 --- a/cfbd/models/recruit_classification.py +++ b/cfbd/models/recruit_classification.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/cfbd/models/season_type.py b/cfbd/models/season_type.py index 3226b752..48255b92 100644 --- a/cfbd/models/season_type.py +++ b/cfbd/models/season_type.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/cfbd/models/season_type_db.py b/cfbd/models/season_type_db.py index c89c6802..f79c3b62 100644 --- a/cfbd/models/season_type_db.py +++ b/cfbd/models/season_type_db.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/cfbd/models/transfer_eligibility.py b/cfbd/models/transfer_eligibility.py index ef4ee63b..bfa570f3 100644 --- a/cfbd/models/transfer_eligibility.py +++ b/cfbd/models/transfer_eligibility.py @@ -12,6 +12,7 @@ Do not edit the class manually. """ # noqa: E501 +from __future__ import annotations import json import pprint diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..d37d2939 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,34 @@ +# Examples + +This directory contains example scripts demonstrating how to use the cfbd Python package. + +## Available Examples + +### basic_usage.py + +A basic example showing how to: +- Configure the API client +- Set up authentication (optional) +- Make API calls to fetch conferences, teams, and games +- Handle API exceptions + +To run this example: + +```bash +python examples/basic_usage.py +``` + +If you have an API key, you can set it as an environment variable: + +```bash +export CFBD_API_KEY='your-api-key-here' +python examples/basic_usage.py +``` + +You can get your API key from [CollegeFootballData.com](https://collegefootballdata.com/key). + +## More Examples + +For more detailed examples and API documentation, see: +- [Main README](../README.md) +- [API Documentation](../docs/) diff --git a/examples/__init__.py b/examples/__init__.py new file mode 100644 index 00000000..a5c80fb7 --- /dev/null +++ b/examples/__init__.py @@ -0,0 +1 @@ +# Examples package diff --git a/examples/basic_usage.py b/examples/basic_usage.py new file mode 100644 index 00000000..0e1225e6 --- /dev/null +++ b/examples/basic_usage.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +""" +Basic usage example for cfbd Python package. + +This example demonstrates how to set up and use the College Football Data API client. +""" + +import os +import cfbd +from cfbd.rest import ApiException + +def main(): + # Configure API client + # You can get your API key from https://collegefootballdata.com/key + configuration = cfbd.Configuration( + host="https://api.collegefootballdata.com" + ) + + # If you have an API key, you can set it like this: + # configuration.access_token = os.environ.get("CFBD_API_KEY") + + # Create API client + with cfbd.ApiClient(configuration) as api_client: + # Create API instances + conferences_api = cfbd.ConferencesApi(api_client) + teams_api = cfbd.TeamsApi(api_client) + games_api = cfbd.GamesApi(api_client) + + print("CFBD Python Client Example") + print("=" * 50) + + try: + # Example 1: Get list of conferences + print("\n1. Fetching conferences...") + conferences = conferences_api.get_conferences() + print(f" Found {len(conferences)} conferences") + if conferences: + print(f" First conference: {conferences[0].name}") + + # Example 2: Get FBS teams + print("\n2. Fetching FBS teams...") + teams = teams_api.get_fbs_teams(year=2023) + print(f" Found {len(teams)} FBS teams for 2023") + if teams: + print(f" First team: {teams[0].school}") + + # Example 3: Get games for a specific year and week + print("\n3. Fetching games...") + games = games_api.get_games(year=2023, week=1, season_type="regular") + print(f" Found {len(games)} games in week 1 of 2023") + if games: + game = games[0] + print(f" First game: {game.home_team} vs {game.away_team}") + + print("\n" + "=" * 50) + print("āœ“ All API calls completed successfully!") + print("\nNote: Some endpoints may require authentication.") + print("Set CFBD_API_KEY environment variable with your API key.") + + except ApiException as e: + print(f"\nāœ— API Exception: {e}") + if e.status == 401: + print(" You may need an API key for this endpoint.") + print(" Get one from: https://collegefootballdata.com/key") + +if __name__ == "__main__": + main()