Setup¶
This document is designed to help you set up your development environment for gfw-api-python-client and serve as a guide and reference for the development process. If you encounter any issues, please open an issue on the issue tracker.
Getting the Source Code¶
To begin working on gfw-api-python-client, you’ll need to obtain the source code. The source code is available on GitHub.
git clone https://github.com/GlobalFishingWatch/gfw-api-python-client.git
cd gfw-api-python-client
Setting Up Your Development Environment¶
gfw-api-python-client is a Python package, and a suitable Python installation (version 3.12 or higher) is required for development. You can download Python from the official website.
We strongly recommend using a virtual environment to isolate the project’s dependencies.
Here’s how to set up your development environment:
python3.12 -m venv .venv
source .venv/bin/activate
Running From Source Tree¶
To run the gfw-api-python-client executable directly from your source tree during development, perform an editable install of gfw-api-python-client within your active virtual environment:
make install
This allows you to develop and test your changes without needing to reinstall the package each time.
Running Tests¶
We use the pytest framework for our tests.
To execute all unit tests:
make test
To execute integration tests (which interact with live APIs):
make test-integration
Running Linters and Code Formatting¶
To maintain a consistent code style, we use pre-commit to manage linters and formatters. pre-commit runs configured checks on your staged files before you commit.
To run all pre-commit checks manually:
make pre-commit
It’s recommended to run these checks before pushing your code.
Building Documentation¶
Our documentation is built using Sphinx. It’s written in a combination of reStructuredText and Markdown (using MyST Parser).
To build the HTML documentation locally:
make docs
The generated HTML files will be in the docs/build/html directory. Open docs/build/html/index.html in your web browser to view the documentation.
For a live-reloading documentation server during development:
make servedocs
Security and Dependency Auditing¶
To check for known security vulnerabilities in our dependencies:
make audit
Useful Make Commands¶
To list all make commands to help you during development at any time:
make help
Next Steps and Useful Resources¶
We encourage you to explore the following resources to better understand the project and our development practices:
Project Specific Resources¶
GitHub Issues: Find tasks, bug reports, and feature requests.
Code of Conduct: Understand community expectations for respectful collaboration.
Contributing Guide: Learn the specific contribution process.
Git Workflow: Branching and commit strategies
Installation: Installation instructions
General Python Development¶
Python Packaging User Guide: Understand Python package structure and distribution.
Python Virtual Environments: Manage project dependencies effectively.
Learn about Git: Master version control.
Learn about GitHub: Familiarize yourself with GitHub’s features.
Understanding the GitHub flow: Learn the standard collaboration workflow.
Dependencies¶
Linting and Code Quality¶
Testing¶
pytest: Testing framework.
pytest-asyncio: Asynchronous testing.
pytest-cov: Test coverage.
pytest-mock: Mocking utilities.
pytest-xdist: Parallel testing.
pytest-timeout: Test timeouts.
Coverage.py: Coverage measurement.
respx: Mocking HTTPX requests.
Development Workflow¶
commitizen: Commit message formatting.
Conventional Commits: Structured commit messages.
pre-commit: Git hook manager.
pip-audit: Dependency vulnerability scanning.
Build and Deployment¶
build: Python build system.
setuptools: Package building.
twine: PyPI uploading.
GitHub Actions: Workflow automation.
Documentation¶
Sphinx: Documentation generation.
MyST - Markedly Structured Text: Markdown-like Sphinx syntax.