Skip to content

Commit b3d0be3

Browse files
yejiyangyejiyang
authored
add auth into client lib and update examples, also remove poetry (#120)
1 parent db39740 commit b3d0be3

33 files changed

+2534
-2155
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,4 +140,7 @@ cython_debug/
140140
# Custom folder to ignore
141141
_to_delete/
142142

143+
# Examples output directory
144+
examples/output/
145+
143146
token_store.json

‎MAINTAINERS_GUIDE.md‎

Lines changed: 175 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,177 @@
11
# Maintainers Guide
22

3-
See the [Makefile](./Makefile) if you need to install and test locally. Just type `make` to get the help.
3+
See the [Makefile](./Makefile) if you need to install and test locally. Just type `make` to get the help.
4+
5+
## 🔧 Build Pipeline and File Preservation
6+
7+
### OpenAPI Client Generation
8+
9+
The field-manager-python-client is automatically generated from OpenAPI specifications using `openapi-python-client`. To ensure custom code is preserved during regeneration:
10+
11+
#### ✅ Files That Are Preserved
12+
- `field_manager_python_client/auth.py` - **Custom authentication module**
13+
- `field_manager_python_client/__init__.py` - **Preserved through custom template**
14+
15+
#### ⚠️ Files That Are Regenerated
16+
- All files in `field_manager_python_client/api/`
17+
- All files in `field_manager_python_client/models/`
18+
- `field_manager_python_client/client.py`
19+
- `field_manager_python_client/errors.py`
20+
- `field_manager_python_client/types.py`
21+
22+
### Custom Template System
23+
24+
The build system uses custom templates in the `templates/` directory:
25+
26+
- `templates/package_init.py.jinja` - **Ensures auth imports are preserved in __init__.py**
27+
- `templates/pyproject.toml.jinja` - Package metadata template
28+
- `templates/README.md.jinja` - Package README template
29+
30+
### Generation Process
31+
32+
```bash
33+
# Full regeneration process
34+
make generate
35+
36+
# This runs:
37+
# 1. Download latest OpenAPI spec
38+
# 2. Extract version info
39+
# 3. Generate client code with custom templates
40+
# 4. Preserve auth.py and custom __init__.py imports
41+
```
42+
43+
### ✅ Verification After Generation
44+
45+
After running `make generate`, verify these files are preserved:
46+
47+
```bash
48+
# Check auth module exists
49+
ls -la field-manager-python-client/field_manager_python_client/auth.py
50+
51+
# Check __init__.py includes auth imports
52+
grep -n "from .auth import" field-manager-python-client/field_manager_python_client/__init__.py
53+
54+
# Should show lines like:
55+
# from .auth import authenticate, get_test_client, get_prod_client, TokenManager
56+
```
57+
58+
## 📚 Examples Directory Management
59+
60+
### Structure
61+
```
62+
examples/
63+
├── setup.py # Automated setup script
64+
├── requirements.txt # Dependencies with version switching
65+
├── README.md # Comprehensive documentation
66+
├── QUICKSTART.md # 5-minute setup guide
67+
├── output/ # Git-ignored output directory
68+
├── examples/ # Example scripts
69+
└── venv/ # Git-ignored virtual environment
70+
```
71+
72+
### Key Features
73+
- **Virtual environment based**: No more Poetry complexity
74+
- **Version switching**: Easy toggle between published/local package
75+
- **Output management**: All outputs go to `output/` directory (git-ignored)
76+
- **Automated setup**: `python setup.py` handles everything
77+
78+
### Adding New Examples
79+
80+
1. **Create the example** in `examples/examples/`
81+
2. **Use new authentication**: `from field_manager_python_client import get_test_client`
82+
3. **Save outputs** to `output/` directory using `Path("output")`
83+
4. **Document clearly** with comments and error handling
84+
5. **Test with both** published and local package versions
85+
86+
## 🚀 Release Process
87+
88+
### 1. Pre-Release Checks
89+
```bash
90+
# Ensure auth.py is preserved
91+
make generate
92+
git status # auth.py should be unchanged
93+
94+
# Test examples work
95+
cd examples
96+
python setup.py --local
97+
source venv/bin/activate
98+
python examples/ex_organizations_new_auth.py
99+
```
100+
101+
### 2. Version Update
102+
- OpenAPI client version is auto-extracted from `openapi.json`
103+
- Update package version if needed in `config.yaml`
104+
105+
### 3. Examples Testing
106+
```bash
107+
cd examples
108+
# Test with published version
109+
python setup.py
110+
source venv/bin/activate
111+
python examples/ex_organizations_new_auth.py
112+
113+
# Test with local version
114+
python setup.py --local
115+
python examples/ex_organizations_new_auth.py
116+
```
117+
118+
## 🔐 Authentication System
119+
120+
### Architecture
121+
The authentication is now integrated into the main package:
122+
123+
- **Module**: `field_manager_python_client/auth.py`
124+
- **Exports**: `authenticate`, `get_test_client`, `get_prod_client`, `TokenManager`
125+
- **Environment configs**: Built-in for test/prod
126+
- **Token management**: Automatic caching and refresh
127+
128+
### Preservation Strategy
129+
The `auth.py` file is **NOT** generated by openapi-python-client, so it's naturally preserved. The `__init__.py` imports are preserved through the custom template `templates/package_init.py.jinja`.
130+
131+
## 🐛 Troubleshooting
132+
133+
### Auth Module Missing After Generation
134+
```bash
135+
# Check if auth.py exists
136+
ls field-manager-python-client/field_manager_python_client/auth.py
137+
138+
# If missing, restore from git
139+
git checkout field-manager-python-client/field_manager_python_client/auth.py
140+
```
141+
142+
### Missing Auth Imports in __init__.py
143+
```bash
144+
# Check custom template
145+
cat templates/package_init.py.jinja
146+
147+
# Regenerate with custom template
148+
make generate
149+
```
150+
151+
### Examples Not Working
152+
```bash
153+
cd examples
154+
# Clean reinstall
155+
rm -rf venv
156+
python setup.py
157+
```
158+
159+
## 🔄 Continuous Integration
160+
161+
### Pipeline Considerations
162+
1. **Test auth preservation**: Verify `auth.py` unchanged after generation
163+
2. **Test examples**: Run examples with both published and local packages
164+
3. **Version compatibility**: Ensure examples work with current package version
165+
166+
### Recommended CI Steps
167+
```bash
168+
# 1. Generate and verify preservation
169+
make generate
170+
git diff --exit-code field-manager-python-client/field_manager_python_client/auth.py
171+
172+
# 2. Test examples setup
173+
cd examples && python setup.py --skip-test
174+
175+
# 3. Test auth imports
176+
python -c "from field_manager_python_client import authenticate; print('OK')"
177+
```

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727

2828
## 🚀 Quick Example
2929

30-
1. Here's a [quick example](./examples/examples/ex_get_project_info_by_id.py) of how to fetch project information using the client:
30+
1. Here's a [quick example](./examples/examples/ex_get_project_details.py) of how to fetch project information using the client:
3131

3232
```python
3333
from field_manager_python_client.api.projects import get_project_projects_project_id_get

‎examples/.gitignore‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Python virtual environment
2+
venv/
3+
.venv/
4+
5+
# Python cache files
6+
__pycache__/
7+
*.py[cod]
8+
*$py.class
9+
10+
# Output directory for examples
11+
output/
12+
13+
# Token files
14+
token_store.json
15+
*.token
16+
17+
# Environment files
18+
.env
19+
.env.local
20+
21+
# Generated files (saved to output/ instead)
22+
*.html
23+
*.xlsx
24+
*.csv
25+
*.json
26+
*.log
27+
28+
# Jupyter Notebook
29+
.ipynb_checkpoints
30+
31+
# IDE files
32+
.vscode/
33+
.idea/
34+
*.swp
35+
*.swo
36+
*~
37+
38+
# OS generated files
39+
.DS_Store
40+
.DS_Store?
41+
._*
42+
.Spotlight-V100
43+
.Trashes
44+
ehthumbs.db
45+
Thumbs.db

‎examples/EXAMPLES_OVERVIEW.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Field Manager API Examples Overview
2+
3+
This directory contains examples demonstrating various Field Manager API capabilities. All examples have been renamed with descriptive, consistent names to make their purpose clear.
4+
5+
## 🔧 Setup
6+
7+
Before running any examples:
8+
9+
1. Install dependencies: `python simple_setup.py`
10+
2. Set your email in environment variables (optional)
11+
12+
## 📋 Available Examples
13+
14+
### 🔐 Authentication
15+
- **`ex_authentication_demo.py`** - Demonstrates authentication methods
16+
- Shows manual authenticate() function usage
17+
- Demonstrates convenience helper functions (get_prod_client, get_test_client)
18+
- Explains automatic token caching and refresh
19+
20+
### 🏢 Organization Management
21+
- **`ex_list_organizations_and_projects.py`** - List organizations and their projects
22+
- Connects to Field Manager API
23+
- Lists all accessible organizations
24+
- Shows project counts for each organization
25+
- Lists projects for the first organization with projects
26+
27+
- **`ex_export_organizations_data.py`** - Export organization data to files
28+
- Exports organization data to JSON, CSV, and text formats
29+
- Creates timestamped output files
30+
- Generates summary reports
31+
32+
### 📁 Project Analysis
33+
- **`ex_get_project_details.py`** - Get detailed project information
34+
- Lists all available projects across organizations
35+
- Retrieves detailed information about specific projects
36+
- Displays project metadata (name, ID, description, creation date)
37+
38+
- **`ex_analyze_organization_projects.py`** - Statistical analysis of organization projects
39+
- Analyzes all projects within an organization
40+
- Calculates statistical metrics (total, average, median locations per project)
41+
- Generates histogram visualization (PNG)
42+
- Exports results to Excel with multiple sheets
43+
- Identifies top projects by location count
44+
45+
### 📍 Location Management
46+
- **`ex_find_duplicate_locations.py`** - Find and visualize duplicate locations
47+
- Detects duplicate locations based on coordinate similarity
48+
- Creates interactive maps with multiple visualization layers
49+
- Generates detailed reports of duplicate findings
50+
- Exports results as HTML map files with clustering
51+
52+
- **`ex_compare_excel_api_locations.py`** - Compare Excel and API location data
53+
- Cross-checks location data between Excel files and API
54+
- Creates sample Excel file if missing
55+
- Identifies discrepancies between data sources
56+
- Exports discrepancy reports to separate Excel files
57+
58+
## 🎯 File Naming Convention
59+
60+
All examples follow the pattern: `ex_[verb]_[object]_[context].py`
61+
62+
Examples:
63+
- `ex_list_organizations_and_projects.py` - Lists organizations and projects
64+
- `ex_find_duplicate_locations.py` - Finds duplicate locations
65+
- `ex_analyze_organization_projects.py` - Analyzes organization projects
66+
- `ex_compare_excel_api_locations.py` - Compares Excel and API locations
67+
68+
## 📤 Output Files
69+
70+
Examples generate various output files in the `output/` directory:
71+
- **Maps**: Interactive HTML files with location data
72+
- **Statistics**: Excel files with analysis results and visualizations
73+
- **Data Export**: JSON, CSV files with organization and project data
74+
- **Reports**: Comparison and analysis reports
75+
76+
## 🚀 Quick Start
77+
78+
1. **Authentication Demo**: `python examples/ex_authentication_demo.py`
79+
2. **List Organizations**: `python examples/ex_list_organizations_and_projects.py`
80+
3. **Project Analysis**: `python examples/ex_analyze_organization_projects.py`
81+
82+
---
83+
84+
**Need help?** Check the main [README.md](../README.md) or individual example files for detailed usage instructions.

‎examples/QUICKSTART.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# 🚀 Quick Start - Field Manager API
2+
3+
## 1. Install
4+
5+
```bash
6+
pip install field-manager-python-client
7+
```
8+
9+
## 2. Run Example
10+
11+
```bash
12+
python examples/ex_list_organizations_and_projects.py
13+
```
14+
15+
## 3. Your First Script
16+
17+
```python
18+
from field_manager_python_client import get_prod_client
19+
20+
# Connect to production environment
21+
client = get_prod_client(email="[email protected]")
22+
23+
# Get organizations
24+
from field_manager_python_client.api.organizations import get_organizations_organizations_get
25+
26+
with client as client:
27+
organizations = get_organizations_organizations_get.sync(client=client)
28+
print(f"Found {len(organizations)} organizations")
29+
```
30+
31+
That's it! 🎉
32+
33+
---
34+
35+
**Need help?** Check the main [README.md](README.md) for troubleshooting.

0 commit comments

Comments
 (0)