You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+37-34Lines changed: 37 additions & 34 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,31 +4,23 @@ This document provides guidance for AI agents working on the `django-cf` reposit
4
4
5
5
### Project Overview
6
6
7
-
`django-cf` is a Django application designed to run on Cloudflare Workers. It utilizes Cloudflare D1 for its database and Durable Objects for stateful operations. The core of this example project is located in `templates/durable-objects/`.
7
+
`django-cf` is a Python package that integrates Django with Cloudflare services. It provides database backends for Cloudflare D1 and Durable Objects, plus middleware for Cloudflare Access authentication. Two complete example projects are provided in the `templates/` directory: one using D1 and one using Durable Objects.
8
8
9
9
### Running Tests
10
10
11
-
The project uses `pnpm` for managing Node.js dependencies and running scripts. The test execution process is defined in `.github/workflows/ci.yml` and can be replicated locally as follows:
11
+
The project uses `npm` for Node.js dependencies and `uv` for Python dependencies. The test execution process is defined in `.github/workflows/ci.yml` and can be replicated locally as follows:
12
12
13
-
1.**Install pnpm**: If you don't have pnpm installed, you can install it globally using npm:
13
+
1.**Install Dependencies**: Navigate to the project root and run:
14
14
```bash
15
-
npm install -g pnpm
15
+
npm install
16
+
uv sync
16
17
```
17
-
2. **Install Project Dependencies**: Navigate to the project root and run:
18
+
This installs both Node.js and Python dependencies required for the project.
19
+
2. **Run Tests**: Execute the tests using:
18
20
```bash
19
-
pnpm install
21
+
pytest
20
22
```
21
-
This command installs both Node.js and Python dependencies required forthe project, including those for the workerin`templates/durable-objects/`.
22
-
3. **Set up Tests**: Run the test setup script:
23
-
```bash
24
-
pnpm run setup-test
25
-
```
26
-
This script typically handles tasks like installing Python development dependencies (e.g., `pytest`, Django) and setting up the Django environment within the worker.
27
-
4. **Run Tests**: Execute the tests using:
28
-
```bash
29
-
pnpm run test
30
-
```
31
-
This command will execute `pytest` which, in turn, uses the `WorkerFixture`in`tests/test_worker.py`. The fixture manages the Cloudflare worker lifecycle (starting `wrangler dev`) for the integration tests.
23
+
This command will execute `pytest` which uses the `WorkerFixture`in`tests/test_worker.py`. The fixture manages the Cloudflare worker lifecycle (starting `wrangler dev`) for the integration tests.
32
24
33
25
**Test Structure Details**:
34
26
* Integration tests are located in the `tests/` directory. This directory must contain an `__init__.py` file to be treated as a package.
@@ -44,37 +36,48 @@ The project uses `pnpm` for managing Node.js dependencies and running scripts. T
44
36
45
37
### Key Files and Directories
46
38
47
-
*`pyproject.toml`: Defines project metadata, Python dependencies, and build settingsfor the wrapper/library aspects.
39
+
*`pyproject.toml`: Defines project metadata, Python dependencies, and build settings.
48
40
*`AGENTS.md`: This file.
49
-
*`templates/durable-objects/`: Contains the actual Django application deployed to Cloudflare.
50
-
*`package.json`: Node.js dependencies for the worker, including `wrangler`.
*`templates/d1/`: Complete Django example using D1 database.
46
+
*`package.json`: Node.js dependencies and npm scripts (`dev`, `deploy`).
47
+
*`wrangler.jsonc`: Wrangler configuration.
48
+
*`pyproject.toml`: Python project configuration.
49
+
*`src/index.py`: Worker entrypoint.
50
+
*`src/app/`: Django project directory.
51
+
*`templates/durable-objects/`: Complete Django example using Durable Objects.
52
+
*`package.json`: Node.js dependencies and npm scripts (`dev`, `deploy`).
53
+
*`wrangler.jsonc`: Wrangler configuration.
54
+
*`pyproject.toml`: Python project configuration.
55
+
*`src/index.py`: Worker entrypoint.
56
+
*`src/app/`: Django project directory.
56
57
*`tests/`: Contains integration tests.
57
58
*`__init__.py`: Makes `tests/` a Python package.
58
-
*`test_worker.py`: Defines the worker fixture and basic setup tests (migrations, admin creation).
59
-
*`test_admin.py`: Contains tests for the Django admin interface (login, logout, etc.).
59
+
*`test_worker.py`: Defines the worker fixture and basic setup tests.
60
+
*`test_admin.py`: Contains tests for the Django admin interface.
60
61
61
62
### Workflow for Future Agents
62
63
63
-
1. **Understand the Setup**: The Django app runs inside a Cloudflare Worker, managed by Wrangler. Tests interact with this via HTTP.
64
-
2. **Dependencies First**: Always ensure both Python (`pip install -e .[dev]`) and Node (`npm install`in the root and `templates/durable-objects/`) dependencies are up to date.
65
-
3. **Write Tests**: For new Django views or functionalities within `templates/durable-objects/src/app/`, add corresponding integration tests in the `tests/` directory.
66
-
4. **Run Tests**: Execute `pytest` to verify changes. Debug any worker startup issues by examining output from the `WorkerFixture`.
67
-
5. **Update AGENTS.md**: If you make significant changes to the testing process, dependency management, or project structure, update this document.
64
+
1. **Understand the Setup**: The `django-cf` package provides backends and middleware for Django on Cloudflare Workers. Two complete templates are provided for reference.
65
+
2. **Dependencies First**: Always ensure both Python (`uv sync`) and Node (`npm install`) dependencies are up to date.
66
+
3. **Database Backends**: The package supports D1 (via `django_cf.db.backends.d1`) and Durable Objects (via `django_cf.db.backends.do`).
67
+
4. **Write Tests**: For new features, add corresponding integration tests in the `tests/` directory.
68
+
5. **Run Tests**: Execute `pytest` to verify changes. Debug any worker startup issues by examining output from the `WorkerFixture`.
69
+
6. **Update AGENTS.md**: If you make significant changes to the testing process, dependency management, or project structure, update this document.
68
70
69
71
### Troubleshooting Tests
70
72
71
73
***`worker failed to start`**:
72
74
* Check the `stdout` and `stderr` printed by the test fixture for errors from `wrangler dev`.
* Verify that the port selected by `get_free_port()` is indeed available.
75
77
***`ImportError: attempted relative import with no known parent package`**: Ensure `tests/__init__.py` exists.
76
-
***`no tests ran` when running `pytest`**: Ensure you are running `pytest` from the root directory of the project. If you are in a subdirectory (e.g., `templates/durable-objects/`), `pytest` might not discover the tests in the `tests/` directory. Running `pytest tests/` from the root should correctly discover and run the tests.
78
+
***`no tests ran` when running `pytest`**: Ensure you are running `pytest` from the root directory of the project. If you are in a subdirectory (e.g., `templates/d1/` or `templates/durable-objects/`), `pytest` might not discover the tests in the `tests/` directory. Running `pytest tests/` from the root should correctly discover and run the tests.
77
79
***CSRF token issues**: The `get_csrf_token` helper in`tests/test_admin.py` is a basic string parser. If Django admin templates change significantly, this helper might need updating (e.g., to use a proper HTML parser).
80
+
***Database backend issues**: Remember that both D1 and Durable Objects have transactions disabled. All queries are committed immediately with no rollback capability.
0 commit comments