a223bcb27a
- env= -> environment= across all docs (Pydantic silently ignores env=) - Remove __version__ check (doesn't exist in module) - Fix APIClient(debug=True) missing required client_id/secret - Fix post.listremoved usage (takes no postId, just lists removed posts) - Fix JS true/false -> Python True/False in code blocks - Fix parameter names: branchName->branch_slug, username->user_slug, postId->post_id - Add missing lastEvaluatedKey param docs for list jobs - Note post.listpublic as unauthenticated endpoint - Fix pagination examples (LastEvaluatedKey, not ExclusiveStartKey dict) - Remove non-existent headers param from make_request example - Fix branch.listbyname example (takes no name arg) - Add 4 missing wrapper docs: follow, react, trust, votecast - Fix broken internal links (case-sensitive filenames) - Fix <environment>_handle_token template artifact - Add CODE_BUGS.md documenting 4 code bugs found during audit
101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
# Code Bugs Found During Documentation Audit
|
|
|
|
This file documents bugs discovered in the source code during the documentation audit on April 18, 2026. These are **not** documentation errors — they are issues in the code itself that affect runtime behavior.
|
|
|
|
---
|
|
|
|
## 1. `trust.listbyusersinit` — Function Name Mismatch
|
|
|
|
**Severity:** High — causes runtime crash
|
|
|
|
**File:** `src/trustcafeapiwrapper/jobs/trust/listbyusersinit.py`
|
|
|
|
**Problem:** The file is named `listbyusersinit.py`, but the function inside is named `listbyuserinit()`. Additionally, `src/trustcafeapiwrapper/jobs/trust/__init__.py` imports `listbyuserinit` (matching the function name), not `listbyusersinit` (matching the file name).
|
|
|
|
**Impact:** Calling `API.run_job('trust.listbyusersinit')` resolves to the *module* object (because Python can import submodules as attributes), not the function. This causes `TypeError: 'module' object is not callable`.
|
|
|
|
**Working alternative:** `API.run_job('trust.listbyuserinit', user_id)` — this resolves to the actual function and works correctly.
|
|
|
|
**Evidence:**
|
|
```python
|
|
API.run_job('trust.listbyusersinit')
|
|
# TypeError: 'module' object is not callable
|
|
|
|
API.run_job('trust.listbyuserinit', 'user123')
|
|
# Resolves correctly, makes API call (will fail auth without real credentials, but function resolution works)
|
|
```
|
|
|
|
**Fix options:**
|
|
- Rename the function from `listbyuserinit` to `listbyusersinit` in `listbyusersinit.py` and update `trust/__init__.py`
|
|
- OR rename the file from `listbyusersinit.py` to `listbyuserinit.py`
|
|
|
|
---
|
|
|
|
## 2. `APIClient.wrapped()` — Docstring Mismatch
|
|
|
|
**Severity:** Low — code works correctly, docstring is wrong
|
|
|
|
**File:** `src/trustcafeapiwrapper/apiclient.py`, method `wrapped()`
|
|
|
|
**Problem:** The docstring says the method expects `'job'` and `'payload'` keys:
|
|
```
|
|
A dictionary with 'job' (string) and 'payload' (dict) keys.
|
|
```
|
|
But the actual code reads `job_function`:
|
|
```python
|
|
return self.run_job(wrapped_data.get("job_function"), wrapped_data.get("payload", {}))
|
|
```
|
|
|
|
**Impact:** No runtime impact — all wrapper functions return `{"job_function": ..., "payload": ...}` which matches what `wrapped()` reads. Only the docstring is misleading.
|
|
|
|
**Fix:** Update docstring from `'job'` to `'job_function'`.
|
|
|
|
---
|
|
|
|
## 3. `env=` Constructor Parameter Silently Ignored
|
|
|
|
**Severity:** High — silent wrong-environment bug
|
|
|
|
**File:** `src/trustcafeapiwrapper/apiclient.py`, class `APIClient`
|
|
|
|
**Problem:** `APIClient` inherits from Pydantic's `BaseModel`. The model defines `environment: str = "alpha"`, but there is no field named `env`. Because Pydantic silently ignores unknown fields by default, passing `env="production"` is **silently discarded** and the environment stays `"alpha"`.
|
|
|
|
**Impact:** Any code using `APIClient(client_id=..., client_secret=..., env="production")` will silently run against the alpha environment instead of production. No error, no warning.
|
|
|
|
**Evidence:**
|
|
```python
|
|
API = APIClient(client_id='test', client_secret='test', env='production')
|
|
print(API.environment) # Prints "alpha" — NOT "production"
|
|
|
|
API = APIClient(client_id='test', client_secret='test', environment='production')
|
|
print(API.environment) # Prints "production" — correct
|
|
```
|
|
|
|
**Fix options:**
|
|
- Add a model validator that raises an error on unknown fields: `model_config = ConfigDict(extra='forbid')`
|
|
- OR add `env` as an alias for `environment`
|
|
|
|
---
|
|
|
|
## 4. Missing `__version__` Attribute
|
|
|
|
**Severity:** Low — not a runtime bug, but a packaging convention
|
|
|
|
**File:** `src/trustcafeapiwrapper/__init__.py`
|
|
|
|
**Problem:** The module does not expose `__version__`. The `__init__.py` only contains:
|
|
```python
|
|
from .apiclient import APIClient
|
|
```
|
|
|
|
**Impact:** Users cannot programmatically check the installed version via `trustcafeapiwrapper.__version__`. This is a standard Python packaging convention.
|
|
|
|
**Fix:** Add to `__init__.py`:
|
|
```python
|
|
from importlib.metadata import version as _get_version
|
|
__version__ = _get_version("trustcafeapiwrapper")
|
|
```
|
|
|
|
---
|
|
|
|
*These bugs were found during a documentation accuracy audit. The documentation has been updated to reflect actual code behavior (e.g., using `environment=` instead of `env=`, documenting `trust.listbyuserinit` as the working job name).*
|