Skip to content

Commit 5e75250

Browse files
jonathanedeyjonathanedey
authored
chore: Added an AGENTS.md file to instruct AI agents how to interact with this repository (#906)
1 parent 6555a84 commit 5e75250

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

‎AGENTS.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Firebase Admin Python SDK - Agent Guide
2+
3+
This document provides AI agents with a comprehensive guide to the conventions, design patterns, and architectural nuances of the Firebase Admin Python SDK. Adhering to this guide ensures that all contributions are idiomatic and align with the existing codebase.
4+
5+
## 1. High-Level Overview
6+
7+
The Firebase Admin Python SDK provides a Pythonic interface to Firebase services. Its design emphasizes thread-safety, a consistent and predictable API, and seamless integration with Google Cloud Platform services.
8+
9+
## 2. Directory Structure
10+
11+
- `firebase_admin/`: The main package directory.
12+
- `__init__.py`: The primary entry point. It exposes the `initialize_app()` function and manages the lifecycle of `App` instances.
13+
- `exceptions.py`: Defines the custom exception hierarchy for the SDK.
14+
- `_http_client.py`: Contains the centralized `JsonHttpClient` and `HttpxAsyncClient` for all outgoing HTTP requests.
15+
- Service modules (e.g., `auth.py`, `db.py`, `messaging.py`): Each module contains the logic for a specific Firebase service.
16+
- `tests/`: Contains all unit tests.
17+
- `tests/resources/`: Contains mock data, keys, and other test assets.
18+
- `integration/`: Contains all integration tests.*
19+
- These integration tests require a real Firebase project to run against.
20+
- `integration/conftest.py`: Contains provides configurations for these integration tests including how credentials are provided through pytest.
21+
- `snippets/`: Contains code snippets used in documentation.
22+
- `setup.py`: Package definition, including the required environment dependencies.
23+
- `requirements.txt`: A list of all development dependencies.
24+
- `.pylintrc`: Configuration file for the `pylint` linter.
25+
- `CONTRIBUTING.md`: General guidelines for human contributors. Your instructions here supersede this file.
26+
27+
## 3. Core Design Patterns
28+
29+
### Initialization
30+
31+
The SDK is initialized by calling the `initialize_app(credential, options)` function. This creates a default `App` instance that SDK modules use implicitly. For multi-project use cases, named apps can be created by providing a `name` argument: `initialize_app(credential, options, name='my_app')`.
32+
33+
### Service Clients
34+
35+
Service clients are accessed via module-level factory functions. These functions automatically use the default app unless a specific `App` object is provided via the `app` parameter. The clients are created lazily and cached for the lifetime of the application.
36+
37+
- **Direct Action Modules (auth, db)**: Some modules provide functions that perform actions directly.
38+
- **Client Factory Modules (firestore, storage)**: Other modules have a function (e.g., client() or bucket()) that returns a client object, which you then use for operations.
39+
40+
41+
### Error Handling
42+
43+
- All SDK-specific exceptions inherit from `firebase_admin.exceptions.FirebaseError`.
44+
- Specific error conditions are represented by subclasses, such as `firebase_admin.exceptions.InvalidArgumentError` and `firebase_admin.exceptions.UnauthenticatedError`.
45+
- Each service may additionaly define exceptions under these subclasses and apply them by passing a handle function to `_utils.handle_platform_error_from_requests()` or `_utils.handle_platform_error_from_httpx()`. Each services error handling patterns should be considered before making changes.
46+
47+
### HTTP Communication
48+
49+
- All synchronous HTTP requests are made through the `JsonHttpClient` class in `firebase_admin._http_client`.
50+
- All asynchronous HTTP requests are made through the `HttpxAsyncClient` class in `firebase_admin._http_client`.
51+
- These clients handle authentication and retries for all API calls.
52+
53+
### Asynchronous Operations
54+
55+
Asynchronous operations are supported using Python's `asyncio` library. Asynchronous methods are typically named with an `_async` suffix (e.g., `messaging.send_each_async()`).
56+
57+
## 4. Coding Style and Naming Conventions
58+
59+
- **Formatting:** This project uses **pylint** to enforce code style and detect potential errors. Before submitting code, you **must** run the linter and ensure your changes do not introduce any new errors. Run the linter from the repository's root directory with the following command:
60+
```bash
61+
./lint.sh all # Lint all source files
62+
```
63+
or
64+
```bash
65+
./lint.sh # Lint locally modified source files
66+
```
67+
- **Naming:**
68+
- Classes: `PascalCase` (e.g., `FirebaseError`).
69+
- Methods and Functions: `snake_case` (e.g., `initialize_app`).
70+
- Private Members: An underscore prefix (e.g., `_http_client`).
71+
- Constants: `UPPER_SNAKE_CASE` (e.g., `INVALID_ARGUMENT`).
72+
73+
## 5. Testing Philosophy
74+
75+
- **Unit Tests:**
76+
- Located in the `tests/` directory.
77+
- Test files follow the `test_*.py` naming convention.
78+
- Unit tests can be run using the following command:
79+
```bash
80+
pytest
81+
```
82+
- **Integration Tests:**
83+
- Located in the `integration/` directory.
84+
- These tests make real API calls to Firebase services and require a configured project. Running these tests be should be ignored without a project and instead rely on the repository's GitHub Actions.
85+
86+
## 6. Dependency Management
87+
88+
- **Manager:** `pip`
89+
- **Manifest:** `requirements.txt`
90+
- **Command:** `pip install -r requirements.txt`
91+
92+
## 7. Critical Developer Journeys
93+
94+
### Journey 1: How to Add a New API Method
95+
96+
1. **Define Public Method:** Add the new method or change to the appropriate service client files (e.g., `firebase_admin/auth.py`).
97+
2. **Expose the public API method** by updating the `__all__` constant with the name of the new method.
98+
3. **Internal Logic:** Implement the core logic within the service package.
99+
4. **HTTP Client:** Use the HTTP client (`JsonHttpClient` or `HttpxAsyncClient`) to make the API call.
100+
5. **Error Handling:** Catching exceptions from the HTTP client and raise the appropriate `FirebaseError` subclass using the services error handling logic
101+
6. **Testing:**
102+
- Add unit tests in the corresponding `test_*.py` file (e.g., `tests/test_user_mgt.py`).
103+
- Add integration tests in the `integration/` directory if applicable.
104+
7. **Snippets:** (Optional) Add or update code snippets in the `snippets/` directory.
105+
106+
### Journey 2: How to Deprecate a Field/Method in an Existing API
107+
108+
1. **Add Deprecation Note:** Locate where the deprecated object is defined and add a deprecation note to its docstring (e.g. `X is deprecated. Use Y instead.`).
109+
2. **Add Deprecation Warning:** In the same location where the deprecated object is defined, add a deprecation warning to the code. (e.g. `warnings.warn('X is deprecated. Use Y instead.', DeprecationWarning)`)
110+
111+
## 8. Critical Do's and Don'ts
112+
113+
- **DO:** Use the centralized `JsonHttpClient` or `HttpxAsyncClient` for all HTTP requests.
114+
- **DO:** Follow the established error handling patterns by using `FirebaseError` and its subclasses.
115+
- **DON'T:** Expose implementation details from private (underscored) modules or functions in the public API.
116+
- **DON'T:** Introduce new third-party dependencies without updating `requirements.txt` and `setup.py`.
117+
118+
## 9. Branch Creation
119+
- When creating a new barnch use the format `agentName-short-description`.
120+
* Example: `jules-auth-token-parsing`
121+
* Example: `gemini-add-storage-file-signer`
122+
123+
## 10. Commit and Pull Request Generation
124+
125+
After implementing and testing a change, you may create a commit and pull request which must follow the following these rules:
126+
127+
### Commit and Pull Request Title Format:
128+
Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification: `type(scope): subject`
129+
- `type` should be one of `feat`, `fix` or `chore`.
130+
- `scope` should be the service package changed (e.g., `auth`, `rtdb`, `deps`).
131+
- **Note**: Some services use specific abbreviations. Use the abbreviation if one exists. Common abbreviations include:
132+
- `messaging` -> `fcm`
133+
- `dataconnect` -> `fdc`
134+
- `database` -> `rtdb`
135+
- `appcheck` -> `fac`
136+
- `subject` should be a brief summary of the change depending on the action:
137+
- For pull requests this should focus on the larger goal the included commits achieve.
138+
- Example: `fix(auth): Resolved issue with custom token verification`
139+
- For commits this should focus on the specific changes made in that commit.
140+
- Example: `fix(auth): Added a new token verification check`
141+
142+
### Commit Body:
143+
This should be a brief explanation of code changes.
144+
145+
Example:
146+
```
147+
feat(fcm): Added `send_each_for_multicast` support for multicast messages
148+
149+
Added a new `send_each_for_multicast` method to the messaging client. This method wraps the `send_each` method and sends the same message to each token.
150+
```
151+
152+
### Pull Request Body:
153+
- A brief explanation of the problem and the solution.
154+
- A summary of the testing strategy (e.g., "Added a new unit test to verify the fix.").
155+
- A **Context Sources** section that lists the `id` and repository path of every `AGENTS.md` file you used.
156+
157+
Example:
158+
```
159+
feat(fcm): Added support for multicast messages
160+
161+
This change introduces a new `send_each_for_multicast` method to the messaging client, allowing developers to send a single message to multiple tokens efficiently.
162+
163+
Testing: Added unit tests in `tests/test_messaging.py` with mock requests and an integration test in `integration/test_messaging.py`.
164+
165+
Context Sources Used:
166+
- id: firebase-admin-python
167+
```
168+
169+
## 11. Metadata
170+
- id: firebase-admin-python

0 commit comments

Comments
 (0)