dotlas/api-client-python

🐍 A python client for the Dotlas REST API and services

api-client-python's Issues

[workflow] Setup & Configure Python Workflow Tools

The following tools can be configured within this project to improve developer workflow. These are already part of a standard template on the Dotlas Cookiecutter Pypackage.

• Poetry for package-level dependency management together with pyproject.toml
• pnpm for package-level build tools from the JS ecosystem:
  • Commitizen for clean commit messages
  • Husky for configuring git hooks
• pre-commit for validating code before committing to the branch. Can check for formatting and linting issues, and blocks code addition to a clean branch if certain rules and parameters are unmet.
  • pre-commit needs to be configured together with husky to run automatically before a commit.

[feat] Incorporate Coverage Endpoints

About

The Dotlas API contains 3 endpoints in the Sociodemographics section that are suffixed to sales territory called coverage. Coverage endpoints essentially create a geographic union of multiple sales territories and return data for the collectively holistic new territory. See example and endpoint schema in the API Docs

These are currently not yet present as python functions in the api-client-python package.

Implementation Goals

• Shapely is recommended as a library to handle the I/O within the python functions.
• Geopandas is not recommended as it contains a heavy requirements list and may bloat up this package and also likely cause installation errors on the client side.

Considerations

Since dotutils already contains shapely functions, it might make sense to make that a requirement for this package. The pros and cons of adding dotutils as a dependency need to be weighed up before moving forward

[docs] Setup Mkdocs Material using Github Pages

About

Currently, our Python codebase lacks proper documentation, which makes it challenging for new contributors and maintainers to understand the codebase's functionality. To address this issue, we need to set up MkDocs Material to generate documentation from the Python function docstrings and deploy it on GitHub Pages.

The goal of this issue is to improve the documentation of our codebase and make it easily accessible to all contributors and maintainers. We will use MkDocs Material to generate documentation from the Python function docstrings. This will allow us to write documentation alongside the code and keep it up to date with any changes made to the code. Furthermore, the documentation will be generated automatically, ensuring that it stays up to date with any changes made to the code.

Steps

The steps involved in this issue are as follows:

1. Install MkDocs Material and any necessary dependencies.
2. Create a new MkDocs project in the root directory of our codebase (docs).
3. Configure MkDocs to generate documentation from the Python function docstrings.
4. Add any additional documentation pages that are required.
5. Deploy the generated documentation to GitHub Pages.

Reference

The [Dotlas Cookiecutter Pypackage] has a template for setting up mkdocs, but does not configure github pages automatically. That can be used as a reference to generate mkdocs for this project.

[tests] [ci] Automated Testing Pipeline

Requirements

This project requires development on the QA and functional tests side. Unit tests for each function that calls the Dotlas API endpoints can be developed with tools such as pytest. The test cases themselves can be enumerated based on valid responses from the API. For ex. if a certain city does not return results - that would be a decent test case to have and flag immediately.

Nice-to-have

Setting up a CI/CD pipeline using Github actions where tests are conducted automatically on the cloud on pushes to certain branches, etc.

[docs] Add docstrings to Pydantic Models

The pydantic models specified in dotlas.schemas requires function docstrings on what each model is used for, and whether or not it is inherited from, or inherited by other models. This will help developers understand the serialized API responses they receive a lot better.

[build] Migrate from `setuptools` to `pyproject.toml`

About

Currently, our Python packages are managed using setuptools using requirements.txt. However, as per the latest industry standards, we need to move towards using pyproject.toml for package management. This will help us in achieving better compatibility and standardization with other tools and platforms.

The pyproject.toml file will contain all the relevant information related to our package, including dependencies, build requirements, linting configurations and project metadata. This will allow us to have a more standardized approach to package management and simplify the process of building, distributing, and installing our packages.

Process

The migration process will involve the following steps:

1. Create a pyproject.toml file in the root directory of the project.
2. Remove setup.py and requirements.txt. Copy the requirements excluding setuptools to pyproject.toml
3. Update the documentation and build scripts to reflect the new package management approach.
4. Test the package installation, building, and distribution process to ensure that everything is working as expected.

Reference

The Dotlas Cookiecutter Pypackage already has a standard template for configuring pyproject.toml. All dependencies mentioned in the template may not be necessary, and some can be removed.