From 6773436906abac45f8ce67581620b5f86803f5c8 Mon Sep 17 00:00:00 2001 From: leonardog Date: Wed, 24 Dec 2025 14:08:33 +0100 Subject: [PATCH 1/3] add agents md --- AGENTS.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..e95e0df3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +## Overview + +This is the Adyen Python API Library, providing Python developers with an easy way to interact with the Adyen API. The library is a wrapper around the Adyen API, generated from OpenAPI specifications. + +## Code Generation + +A significant portion of this library, particularly the API services, is automatically generated. + +- **Engine**: We use [OpenAPI Generator](https://openapi-generator.tech/) with custom [Mustache](https://mustache.github.io/) templates to convert Adyen's OpenAPI specifications into Python code. +- **Templates**: The custom templates are located in the `/templates` directory. These templates are tailored to fit our custom HTTP client and service structure. +- **Automation**: + - **Centralized**: The primary generation process is managed in a separate repository, [`adyen-sdk-automation`](https://github.com/Adyen/adyen-sdk-automation). Changes to the OpenAPI specs trigger a GitHub workflow in that repository, which generates the code and opens Pull Requests in this library. + - **Local**: For development and testing, you must use the [`adyen-sdk-automation`](https://github.com/Adyen/adyen-sdk-automation) repository. + +### Local Code Generation + +To test new features or changes to the templates, you must run the generation process from a local clone of the `adyen-sdk-automation` repository. + +1. **Clone the automation repository**: + ```bash + git clone https://github.com/Adyen/adyen-sdk-automation.git + ``` + +2. **Link this library**: The automation project needs to target your local clone of `adyen-python-api-library`. From inside the `adyen-sdk-automation` directory, run the following commands. This will replace the `python/repo` directory with a symlink to your local project. + ```bash + rm -rf python/repo + ln -s /path/to/your/adyen-python-api-library python/repo + ``` + +3. **Run the generator**: You can now run the Gradle commands to generate code. + - **To generate all services for the Python library**: + ```bash + ./gradlew :python:services + ``` + - **To generate a single service (e.g., Checkout)**: + ```bash + ./gradlew :python:checkout + ``` + - **To clean the repository before generating**: + ```bash + ./gradlew :python:cleanRepo :python:checkout + ``` + +## Core Components + +- **`Adyen.Adyen`**: The main facade class in `Adyen/__init__.py` that provides easy access to all API services. +- **`Adyen.client.AdyenClient`**: The central class for configuring the library (API key, environment, etc.) and making API calls. +- **`Adyen.httpclient.HTTPClient`**: The underlying client responsible for making HTTP requests to the Adyen API. +- **`Adyen/services/`**: This package contains the generated service classes (e.g., `AdyenCheckoutApi`, `AdyenManagementApi`) that expose methods for specific API endpoints. Unlike some other Adyen libraries, this one does not use generated models for requests and responses; standard Python dictionaries are used instead. + +## Development Workflow + +This project uses `make` and `tox` to streamline development tasks. + +### Setup + +To install the library and its development dependencies, run: +```bash +make install +``` + +### Running Tests + +To execute the unit tests across different Python versions: +```bash +make test +``` +This command runs `tox`, which manages the test environments. + +### Code Style & Formatting + +We use `flake8` for linting and `black` for formatting. + +- **Check for style violations and type errors**: + ```bash + make lint + ``` +- **Apply formatting**: + ```bash + make format + ``` + +The build will fail if there are any linting violations. Run `make format` before committing. + +## Release Process + +The release process is automated via GitHub Actions. When a release is triggered: +1. A script determines the next version number (major, minor, or patch). +2. The `VERSION` file and other configuration files are updated. +3. A pull request is created with the version bump. +4. Once merged, a GitHub release is created, and the new version is published to PyPI. From a65a1e8d18fe71e9b3777693147c82cf4137c170 Mon Sep 17 00:00:00 2001 From: Leonardo Galesky Date: Wed, 24 Dec 2025 14:15:15 +0100 Subject: [PATCH 2/3] Update AGENTS.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e95e0df3..ab06e993 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,10 +21,10 @@ To test new features or changes to the templates, you must run the generation pr git clone https://github.com/Adyen/adyen-sdk-automation.git ``` -2. **Link this library**: The automation project needs to target your local clone of `adyen-python-api-library`. From inside the `adyen-sdk-automation` directory, run the following commands. This will replace the `python/repo` directory with a symlink to your local project. +2. **Link this library**: The automation project needs to target your local clone of `adyen-python-api-library`. From inside the `adyen-sdk-automation` directory, run the following commands. This will replace the `python/repo` directory with a symlink to your local project. For example, if you cloned both repositories in the same parent directory: ```bash rm -rf python/repo - ln -s /path/to/your/adyen-python-api-library python/repo + ln -s ../adyen-python-api-library python/repo ``` 3. **Run the generator**: You can now run the Gradle commands to generate code. From bcd37b2a4e9a0be3de6d2086d74ab6c4684f9e6a Mon Sep 17 00:00:00 2001 From: leonardog Date: Wed, 24 Dec 2025 14:21:13 +0100 Subject: [PATCH 3/3] update make references --- AGENTS.md | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ab06e993..57fdb2c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,26 +61,19 @@ make install ### Running Tests -To execute the unit tests across different Python versions: -```bash -make test -``` -This command runs `tox`, which manages the test environments. - -### Code Style & Formatting - -We use `flake8` for linting and `black` for formatting. +You can run the unit tests using two main methods: -- **Check for style violations and type errors**: - ```bash - make lint - ``` -- **Apply formatting**: - ```bash - make format - ``` +1. **Directly via `make`**: For a quick run of the test suite in your current environment. + ```bash + make tests + ``` + This command executes the tests using Python's built-in `unittest` module. -The build will fail if there are any linting violations. Run `make format` before committing. +2. **Via `tox`**: For comprehensive testing across multiple Python versions, as is done in the CI pipeline. + ```bash + tox + ``` + This command uses the `tox.ini` configuration to create isolated environments and run tests in each, ensuring compatibility. This is the method used in our GitHub Actions workflow. ## Release Process