Skip to content

Commit 9147028

Browse files
winridwinrid
committed
Release prep
1 parent aaa2dbb commit 9147028

File tree

5 files changed

+242
-29
lines changed

5 files changed

+242
-29
lines changed

‎README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# fastcomments-python
2+
The FastComments Python SDK. You can use this to build secure and scalable backend applications that interact with FastComments, or build reactive client applications.
3+
4+
## Installation
5+
6+
### PyPI
7+
8+
```bash
9+
pip install fastcomments-python
10+
```
11+
12+
### Library Contents
13+
14+
This library contains two modules: the generated API client and the core Python library which contains hand-written utilities to make working with the API easier, including SSO support.
15+
16+
- [API Client Library Docs](./client/README.md)
17+
- [Core Library Docs, Including SSO Examples](./sso/README.md)
18+
19+
### Public vs Secured APIs
20+
21+
For the API client, there are two classes, `DefaultApi` and `PublicApi`. The `DefaultApi` contains methods that require your API key, and `PublicApi` contains API calls that can be made directly from a browser/mobile device/etc without authentication.
22+
23+
## Quick Start
24+
25+
### Using Authenticated APIs (DefaultApi)
26+
27+
**Important:** You must set your API key on the Configuration before making authenticated requests. If you don't, requests will fail with a 401 error.
28+
29+
```python
30+
from client import ApiClient, Configuration, DefaultApi
31+
from client.models import CreateAPISSOUserData
32+
33+
# Create and configure the API client
34+
config = Configuration()
35+
config.host = "https://fastcomments.com/api"
36+
37+
# REQUIRED: Set your API key (get this from your FastComments dashboard)
38+
config.api_key = {"ApiKeyAuth": "YOUR_API_KEY_HERE"}
39+
40+
# Create the API instance with the configured client
41+
api_client = ApiClient(configuration=config)
42+
api = DefaultApi(api_client)
43+
44+
# Now you can make authenticated API calls
45+
try:
46+
# Example: Add an SSO user
47+
user_data = CreateAPISSOUserData(
48+
id="user-123",
49+
email="user@example.com",
50+
display_name="John Doe"
51+
)
52+
53+
response = api.add_sso_user(
54+
tenant_id="YOUR_TENANT_ID",
55+
create_apisso_user_data=user_data
56+
)
57+
print(f"User created: {response}")
58+
59+
except Exception as e:
60+
print(f"Error: {e}")
61+
# Common errors:
62+
# - 401: API key is missing or invalid
63+
# - 400: Request validation failed
64+
```
65+
66+
### Using Public APIs (PublicApi)
67+
68+
Public endpoints don't require authentication:
69+
70+
```python
71+
from client import ApiClient, Configuration, PublicApi
72+
73+
config = Configuration()
74+
config.host = "https://fastcomments.com/api"
75+
76+
api_client = ApiClient(configuration=config)
77+
public_api = PublicApi(api_client)
78+
79+
try:
80+
response = public_api.get_comments_public(
81+
tenant_id="YOUR_TENANT_ID",
82+
url_id="page-url-id"
83+
)
84+
print(response)
85+
except Exception as e:
86+
print(f"Error: {e}")
87+
```
88+
89+
### Using SSO (Single Sign-On)
90+
91+
The SDK includes utilities for generating secure SSO tokens:
92+
93+
```python
94+
from sso import FastCommentsSSO, SecureSSOUserData
95+
96+
# Create user data
97+
user_data = SecureSSOUserData(
98+
user_id="user-123",
99+
email="user@example.com",
100+
username="johndoe",
101+
avatar="https://example.com/avatar.jpg"
102+
)
103+
104+
# Create SSO instance with your API secret
105+
sso = FastCommentsSSO.new_secure(
106+
api_secret="YOUR_API_SECRET",
107+
user_data=user_data
108+
)
109+
110+
# Generate the SSO token
111+
sso_token = sso.create_token()
112+
113+
# Use this token in your frontend or pass to API calls
114+
print(f"SSO Token: {sso_token}")
115+
```
116+
117+
For simple SSO (less secure, for testing):
118+
119+
```python
120+
from sso import FastCommentsSSO, SimpleSSOUserData
121+
122+
user_data = SimpleSSOUserData(
123+
user_id="user-123",
124+
email="user@example.com"
125+
)
126+
127+
sso = FastCommentsSSO.new_simple(user_data)
128+
sso_token = sso.create_token()
129+
```
130+
131+
### Common Issues
132+
133+
1. **401 "missing-api-key" error**: Make sure you set `config.api_key = {"ApiKeyAuth": "YOUR_KEY"}` before creating the DefaultApi instance.
134+
2. **Wrong API class**: Use `DefaultApi` for server-side authenticated requests, `PublicApi` for client-side/public requests.
135+
3. **Import errors**: Make sure you're importing from the correct module:
136+
- API client: `from client import ...`
137+
- SSO utilities: `from sso import ...`
138+
139+
## Development
140+
141+
### Running Tests
142+
143+
```bash
144+
# Set up environment variables
145+
export FASTCOMMENTS_API_KEY="your-api-key"
146+
export FASTCOMMENTS_TENANT_ID="your-tenant-id"
147+
148+
# Run tests
149+
pytest tests/
150+
```
151+
152+
### Regenerating the Client
153+
154+
To regenerate the API client from the latest OpenAPI specification:
155+
156+
```bash
157+
./update.sh
158+
```
159+
160+
This will:
161+
1. Download the latest OpenAPI spec from a running FastComments server (or use local openapi.yaml)
162+
2. Generate the Python client code
163+
3. Flatten the directory structure
164+
4. Clean up redundant configuration files
165+
166+
## Notes
167+
168+
### Broadcast IDs
169+
170+
You'll see you're supposed to pass a `broadcast_id` in some API calls. When you receive events, you'll get this ID back, so you know to ignore the event if you plan to optimistically apply changes on the client (which you'll probably want to do since it offers the best experience). Pass a UUID here. The ID should be unique enough to not occur twice in a browser session.
171+
172+
## Requirements
173+
174+
- Python >= 3.8
175+
- urllib3 >= 1.25.3
176+
- python-dateutil >= 2.8.2
177+
- pydantic >= 2.0.0
178+
- typing-extensions >= 4.0.0
179+
180+
## License
181+
182+
MIT
183+
184+
## Support
185+
186+
- [Documentation](https://docs.fastcomments.com)
187+
- [GitHub Issues](https://github.com/fastcomments/fastcomments-python/issues)
188+
- [FastComments Support](https://fastcomments.com/auth/my-account/help)

‎client/.openapi-generator-ignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,6 @@
2121
#docs/*.md
2222
# Then explicitly reverse the ignore rule for a single file:
2323
#!docs/README.md
24+
25+
# Don't regenerate README - we have a custom one
26+
README.md

‎client/README.md‎

Lines changed: 22 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,43 @@
1-
# fastcomments-python
2-
No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
1+
# FastComments API Client
32

4-
This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
3+
The FastComments API client for Python. This package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project.
54

6-
- API version: 0.0.0
5+
- API version: 0.0.1
76
- Package version: 0.0.1
87
- Generator version: 7.11.0
98
- Build package: org.openapitools.codegen.languages.PythonClientCodegen
109

10+
**Note:** This is a submodule of the `fastcomments-python` package. For general usage, please refer to the [main package README](../README.md).
11+
1112
## Requirements.
1213

1314
Python 3.8+
1415

1516
## Installation & Usage
1617
### pip install
1718

18-
If the python package is hosted on a repository, you can install directly using:
19+
Install the main package:
1920

2021
```sh
21-
pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git
22+
pip install fastcomments-python
2223
```
23-
(you may need to run `pip` with root permission: `sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git`)
2424

25-
Then import the package:
25+
Then import the client module:
2626
```python
27-
import generated
27+
from client import ApiClient, Configuration, DefaultApi, PublicApi
2828
```
2929

3030
### Setuptools
3131

32-
Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
32+
Or install from source:
3333

3434
```sh
35-
python setup.py install --user
35+
pip install -e .
3636
```
37-
(or `sudo python setup.py install` to install the package for all users)
3837

39-
Then import the package:
38+
Then import the client module:
4039
```python
41-
import generated
40+
from client import ApiClient, Configuration, DefaultApi, PublicApi
4241
```
4342

4443
### Tests
@@ -51,25 +50,21 @@ Please follow the [installation procedure](#installation--usage) and then run th
5150

5251
```python
5352

54-
import generated
55-
from generated.rest import ApiException
53+
from client import ApiClient, Configuration, PublicApi
54+
from client.exceptions import ApiException
5655
from pprint import pprint
5756

58-
# Defining the host is optional and defaults to https://fastcomments.com
59-
# See configuration.py for a list of all supported configuration parameters.
60-
configuration = generated.Configuration(
61-
host = "https://fastcomments.com"
57+
# Configure the host (defaults to FastComments production API)
58+
configuration = Configuration(
59+
host = "https://fastcomments.com/api"
6260
)
6361

64-
65-
6662
# Enter a context with an instance of the API client
67-
with generated.ApiClient(configuration) as api_client:
63+
with ApiClient(configuration) as api_client:
6864
# Create an instance of the API class
69-
api_instance = generated.PublicApi(api_client)
70-
tenant_id = 'tenant_id_example' # str |
71-
comment_id = 'comment_id_example' # str |
72-
public_block_from_comment_params = generated.PublicBlockFromCommentParams() # PublicBlockFromCommentParams |
65+
api_instance = PublicApi(api_client)
66+
tenant_id = 'YOUR_TENANT_ID' # str | Your FastComments tenant ID
67+
url_id = 'my-page' # str | The URL identifier for the page
7368
sso = 'sso_example' # str | (optional)
7469

7570
try:

‎pyproject.toml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,14 @@ name = "fastcomments-python"
77
version = "0.0.1"
88
description = "FastComments Python SDK - A SDK for interacting with the FastComments API"
99
readme = "README.md"
10-
license = {text = "MIT"}
10+
license = "MIT"
1111
authors = [
1212
{name = "FastComments", email = "support@fastcomments.com"}
1313
]
1414
requires-python = ">=3.8"
1515
classifiers = [
1616
"Development Status :: 3 - Alpha",
1717
"Intended Audience :: Developers",
18-
"License :: OSI Approved :: MIT License",
1918
"Programming Language :: Python :: 3",
2019
"Programming Language :: Python :: 3.8",
2120
"Programming Language :: Python :: 3.9",

‎update.sh‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,17 @@ if [ -d "./client/client" ]; then
3030
echo "Flattened nested client directory structure"
3131
fi
3232

33+
# Remove redundant/conflicting generated configs (we use root pyproject.toml)
34+
if [ -f "./client/pyproject.toml" ]; then
35+
rm ./client/pyproject.toml
36+
echo "Removed redundant client/pyproject.toml"
37+
fi
38+
39+
if [ -f "./client/setup.py" ]; then
40+
rm ./client/setup.py
41+
echo "Removed redundant client/setup.py"
42+
fi
43+
3344
echo "Generated Python client in ./client"
3445

3546
# Generate API documentation (optional)
@@ -42,3 +53,20 @@ npx @openapitools/openapi-generator-cli generate \
4253
-c openapi-config.json
4354

4455
echo "Generated API documentation in ./docs/api"
56+
57+
# Clean up old build artifacts
58+
echo "Cleaning old build artifacts..."
59+
rm -rf ./dist ./build ./*.egg-info
60+
61+
# Rebuild the package
62+
echo "Building package..."
63+
python -m build
64+
65+
if [ $? -eq 0 ]; then
66+
echo "✓ Package built successfully!"
67+
echo " Artifacts in ./dist/"
68+
ls -lh ./dist/
69+
else
70+
echo "✗ Build failed!"
71+
exit 1
72+
fi

0 commit comments

Comments
 (0)