Skip to content

Commit 26c4d06

Browse files
funkatronfunkatron
committed
docs: add informative docs to project_docs folder, mainly for historical reasons. if confusing, disponse of them
1 parent 19f1db5 commit 26c4d06

File tree

3 files changed

+230
-0
lines changed

3 files changed

+230
-0
lines changed

‎project-docs/List_API_Endpoint_Test_Mapping.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# List API Endpoint to Test Mapping
2+
3+
This document maps the Geocodio List API endpoints to the client methods and test methods in the Python client.
4+
5+
## Mapping Table
6+
7+
| API Endpoint | HTTP Method | Client Method | Test Method | Description |
8+
|--------------|-------------|---------------|-------------|-------------|
9+
| `/v1.8/lists` | POST | `create_list()` | `test_create_list()` | Create a new list |
10+
| `/v1.8/lists` | GET | `get_lists()` | `test_get_lists()` | Retrieve all lists |
11+
| `/v1.8/lists/{list_id}` | GET | `get_list()` | `test_get_list()` | Retrieve a specific list |
12+
| `/v1.8/lists/{list_id}` | PUT | `update_list()` | `test_update_list()` | Update a list |
13+
| `/v1.8/lists/{list_id}` | DELETE | `delete_list()` | `test_delete_list()` | Delete a list |
14+
| `/v1.8/lists/{list_id}/items` | POST | `add_items_to_list()` | `test_add_items_to_list()` | Add items to a list |
15+
| `/v1.8/lists/{list_id}/items` | DELETE | `remove_items_from_list()` | `test_remove_items_from_list()` | Remove items from a list |
16+
| `/v1.8/lists/{list_id}/geocode` | GET | `geocode_list()` | `test_geocode_list()` | Geocode all items in a list |
17+
18+
## Test Coverage
19+
20+
All List API endpoints are covered by end-to-end tests in the `tests/e2e/test_lists_api.py` file. These tests make real API calls to the Geocodio API and verify the responses.
21+
22+
The tests use a `client` fixture that creates a `GeocodioClient` instance using the API key from the environment variable, and a `test_list` fixture that creates a test list for use in the tests and cleans it up afterward.
23+
24+
## Test Implementation Details
25+
26+
Each test follows a similar pattern:
27+
1. Call the client method with appropriate parameters
28+
2. Verify the response structure and content
29+
3. Clean up any created resources
30+
31+
For example, the `test_create_list()` method:
32+
1. Calls `client.create_list()` with a name and description
33+
2. Verifies that the response contains a list with the correct name and description
34+
3. Cleans up by deleting the created list
35+
36+
This ensures that the tests are isolated and don't leave test data in the API.

‎project-docs/List_API_Implementation_Plan.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# List API Implementation Plan
2+
3+
## Overview
4+
The List API allows users to manage lists of addresses or coordinates for batch processing. This document outlines the tasks required to implement the List API functionality in the Geocodio Python client.
5+
6+
## Task List
7+
8+
### 1. Research and Design
9+
- [ ] Research the Geocodio List API documentation
10+
- [ ] Understand the List API endpoints and parameters
11+
- [ ] Design the Python interface for the List API
12+
- [ ] Define the data models for List API responses
13+
14+
### 2. Implementation
15+
- [ ] Add List API models to models.py
16+
- [ ] Create ListResponse class
17+
- [ ] Create ListItem class
18+
- [ ] Create List class
19+
- [ ] Implement List API methods in client.py
20+
- [ ] create_list() - Create a new list
21+
- [ ] get_list() - Retrieve a list by ID
22+
- [ ] get_lists() - Retrieve all lists
23+
- [ ] update_list() - Update a list
24+
- [ ] delete_list() - Delete a list
25+
- [ ] add_items_to_list() - Add items to a list
26+
- [ ] remove_items_from_list() - Remove items from a list
27+
- [ ] geocode_list() - Geocode all items in a list
28+
29+
### 3. Testing
30+
- [ ] Write unit tests for List API models
31+
- [ ] Write unit tests for List API methods
32+
- [ ] Write integration tests for List API functionality
33+
- [ ] Ensure test coverage for edge cases
34+
35+
### 4. Documentation
36+
- [ ] Update README.md with List API examples
37+
- [ ] Add docstrings to List API methods
38+
- [ ] Create usage examples for List API
39+
40+
### 5. Validation
41+
- [ ] Verify List API functionality with real API calls
42+
- [ ] Ensure error handling for List API methods
43+
- [ ] Check performance for large lists
44+
45+
## Implementation Details
46+
47+
### List API Endpoints
48+
Based on the existing API patterns, the List API endpoints are likely:
49+
- `POST /v1.8/lists` - Create a new list
50+
- `GET /v1.8/lists` - Retrieve all lists
51+
- `GET /v1.8/lists/{list_id}` - Retrieve a specific list
52+
- `PUT /v1.8/lists/{list_id}` - Update a list
53+
- `DELETE /v1.8/lists/{list_id}` - Delete a list
54+
- `POST /v1.8/lists/{list_id}/items` - Add items to a list
55+
- `DELETE /v1.8/lists/{list_id}/items` - Remove items from a list
56+
- `GET /v1.8/lists/{list_id}/geocode` - Geocode all items in a list
57+
58+
### Data Models
59+
The List API will likely require the following data models:
60+
- `List` - Represents a list of addresses or coordinates
61+
- `ListItem` - Represents an item in a list
62+
- `ListResponse` - Represents the response from the List API
63+
64+
### Client Methods
65+
The GeocodioClient class will be extended with the following methods:
66+
- `create_list(name, description=None, items=None)` - Create a new list
67+
- `get_list(list_id)` - Retrieve a list by ID
68+
- `get_lists()` - Retrieve all lists
69+
- `update_list(list_id, name=None, description=None)` - Update a list
70+
- `delete_list(list_id)` - Delete a list
71+
- `add_items_to_list(list_id, items)` - Add items to a list
72+
- `remove_items_from_list(list_id, item_ids)` - Remove items from a list
73+
- `geocode_list(list_id, fields=None)` - Geocode all items in a list
74+
75+
## Next Steps
76+
1. Confirm the List API requirements with the Geocodio API documentation
77+
2. Begin implementation of the List API models
78+
3. Implement the List API methods in the client
79+
4. Write tests for the List API functionality
80+
5. Update documentation with List API examples

‎project-docs/List_API_Implementation_Summary.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# List API Implementation Summary
2+
3+
## Overview
4+
5+
This document summarizes the implementation of the List API functionality in the Geocodio Python client. The List API allows users to manage lists of addresses or coordinates for batch processing.
6+
7+
## Changes Made
8+
9+
### 1. Added List API Models
10+
11+
Added the following data models to `src/geocodio/models.py`:
12+
13+
- `ListItem`: Represents an item in a list, with properties like id, query, created_at, updated_at, geocoded_at, and result.
14+
- `GeocodioList`: Represents a list of addresses or coordinates, with properties like id, name, description, created_at, updated_at, item_count, and items.
15+
- `ListResponse`: Represents the top-level structure returned by list API methods, with properties like lists, list, item, and items.
16+
17+
### 2. Implemented List API Methods
18+
19+
Added the following methods to the `GeocodioClient` class in `src/geocodio/client.py`:
20+
21+
- `create_list()`: Create a new list
22+
- `get_lists()`: Retrieve all lists
23+
- `get_list()`: Retrieve a list by ID
24+
- `update_list()`: Update a list
25+
- `delete_list()`: Delete a list
26+
- `add_items_to_list()`: Add items to a list
27+
- `remove_items_from_list()`: Remove items from a list
28+
- `geocode_list()`: Geocode all items in a list
29+
30+
Also added helper methods for parsing the responses from the List API:
31+
- `_parse_list_response()`: Parse a response from the List API
32+
- `_parse_list_item()`: Parse a list item from the List API
33+
34+
### 3. Added Tests for List API
35+
36+
Created a new test file `tests/test_lists.py` with tests for all List API methods:
37+
38+
- `test_create_list`: Tests creating a new list
39+
- `test_get_lists`: Tests retrieving all lists
40+
- `test_get_list`: Tests retrieving a list by ID
41+
- `test_update_list`: Tests updating a list
42+
- `test_delete_list`: Tests deleting a list
43+
- `test_add_items_to_list`: Tests adding items to a list
44+
- `test_remove_items_from_list`: Tests removing items from a list
45+
- `test_geocode_list`: Tests geocoding all items in a list
46+
47+
### 4. Updated Documentation
48+
49+
Updated the README.md file to include documentation for the List API functionality, with examples of how to use all the List API methods.
50+
51+
### 5. Created Example Script
52+
53+
Created an example script `examples/list_api_example.py` that demonstrates a complete workflow for using the List API, from creating a list to deleting it.
54+
55+
## List API Endpoints
56+
57+
The List API uses the following endpoints:
58+
59+
- `POST /v1.8/lists`: Create a new list
60+
- `GET /v1.8/lists`: Retrieve all lists
61+
- `GET /v1.8/lists/{list_id}`: Retrieve a specific list
62+
- `PUT /v1.8/lists/{list_id}`: Update a list
63+
- `DELETE /v1.8/lists/{list_id}`: Delete a list
64+
- `POST /v1.8/lists/{list_id}/items`: Add items to a list
65+
- `DELETE /v1.8/lists/{list_id}/items`: Remove items from a list
66+
- `GET /v1.8/lists/{list_id}/geocode`: Geocode all items in a list
67+
68+
## Usage Example
69+
70+
```python
71+
from geocodio import
72+
73+
GeocodioClient
74+
75+
# Initialize the client with your API key
76+
client = GeocodioClient(
77+
"YOUR_API_KEY")
78+
79+
# Create a new list
80+
new_list = client.create_list(
81+
format_="{{A}}")
82+
83+
# Get a specific list
84+
list_id = new_list.list.id
85+
list_details = client.get_list(
86+
list_id)
87+
88+
# Geocode all items in a list
89+
geocoded_list = client.geocode_list(
90+
list_id=list_id,
91+
fields=[
92+
"timezone",
93+
"cd"]
94+
)
95+
96+
# Access geocoded results
97+
for item in geocoded_list.list.items:
98+
if item.result:
99+
print(
100+
f"{item.query} => {item.result.formatted_address}")
101+
print(
102+
f"Location: {item.result.location.lat}, {item.result.location.lng}")
103+
```
104+
105+
## Next Steps
106+
107+
The List API implementation is now complete and ready for use. Users can manage lists of addresses or coordinates and geocode them in batch using the new List API methods.
108+
109+
For future enhancements, consider:
110+
111+
1. Adding pagination support for retrieving large lists
112+
2. Implementing rate limiting for List API requests
113+
3. Adding support for filtering and sorting lists
114+
4. Implementing caching for frequently accessed lists

0 commit comments

Comments
 (0)