Skip to content

Commit c06db34

Browse files
ivankamkinivankamkin
committed
Add skill
1 parent f74bd27 commit c06db34

4 files changed

Lines changed: 294 additions & 0 deletions

File tree

‎skills/aspose-barcode-cloud-python/SKILL.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
name: aspose-barcode-cloud-python
3+
description: Write or update Python code that uses the Aspose.BarCode Cloud SDK (`aspose_barcode_cloud`; pip package `aspose-barcode-cloud`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in Python, touches files under `submodules/python`, or mentions `GenerateApi`, `RecognizeApi`, `ScanApi`, `ApiClient`, `Configuration`, `GenerateParams`, `RecognizeBase64Request`, or `ScanBase64Request`. The SDK has several easy-to-miss idioms, including constructing APIs from `ApiClient(Configuration(...))`, reading generate results from `.data`, using public `file_url` values for GET recognize and scan methods, base64-encoding body payloads yourself, and remembering that the install and import names differ.
4+
---
5+
6+
# Aspose.BarCode Cloud SDK for Python
7+
8+
The Python SDK is a thin generated client over the Aspose BarCode Cloud REST API. Most tasks come down to choosing the right API class (`GenerateApi`, `RecognizeApi`, or `ScanApi`), choosing the right transport variant (GET, base64 body, or multipart), and wiring `Configuration` into `ApiClient` correctly.
9+
10+
The package name and import name differ. Install `aspose-barcode-cloud`, then import from `aspose_barcode_cloud`.
11+
12+
## Quick start
13+
14+
Use these imports in most Python examples:
15+
16+
```python
17+
from aspose_barcode_cloud import (
18+
ApiClient,
19+
Configuration,
20+
GenerateApi,
21+
RecognizeApi,
22+
ScanApi,
23+
)
24+
```
25+
26+
Prefer constructing API classes from one shared `ApiClient`:
27+
28+
```python
29+
config = Configuration(
30+
client_id=client_id,
31+
client_secret=client_secret,
32+
)
33+
api_client = ApiClient(configuration=config)
34+
35+
generate_api = GenerateApi(api_client=api_client)
36+
recognize_api = RecognizeApi(api_client=api_client)
37+
scan_api = ScanApi(api_client=api_client)
38+
```
39+
40+
If the task is repo maintenance inside `submodules/python`, read `references/repo-workflow.md`. If the task needs the closest existing example or snippet, read `references/snippet-map.md`.
41+
42+
## Authentication
43+
44+
Use one of these two patterns:
45+
46+
1. Let the SDK fetch an access token lazily from client credentials.
47+
48+
```python
49+
config = Configuration(
50+
client_id=client_id,
51+
client_secret=client_secret,
52+
)
53+
```
54+
55+
2. Inject a pre-fetched bearer token.
56+
57+
```python
58+
config = Configuration(
59+
access_token=token,
60+
host="https://api.aspose.cloud/v4.0",
61+
)
62+
```
63+
64+
`Configuration.access_token` fetches a token automatically when `_access_token` is empty but `client_id`, `client_secret`, and `token_url` are present.
65+
66+
Inside this repo, tests load `tests/configuration.json` first and then fall back to `TEST_CONFIGURATION_*` environment variables. Snippets usually check `TEST_CONFIGURATION_ACCESS_TOKEN` first, then fall back to client credentials. Mirror the surrounding file when editing existing repo code.
67+
68+
`Configuration` defaults to `host="https://api.aspose.cloud/v4.0"` and `token_url="https://id.aspose.cloud/connect/token"`. Some older repo artifacts still mention the v3.0 host; prefer the runtime default unless you are intentionally matching older behavior in that file.
69+
70+
## Choose the right API shape
71+
72+
Pick the operation first:
73+
74+
- `GenerateApi`: create a barcode image.
75+
- `RecognizeApi`: decode one or more known barcode types and optionally tune recognition.
76+
- `ScanApi`: auto-detect barcode types with the smallest API surface.
77+
78+
Then pick the transport variant based on what the caller has:
79+
80+
- Public internet URL to an image: use `recognize()` or `scan()`. `file_url` must be a public URL, not a local path.
81+
- Local file object or stream: use `recognize_multipart()` or `scan_multipart()`.
82+
- Raw bytes already in memory: base64-encode them yourself and use `recognize_base64()` or `scan_base64()`.
83+
- Simple text plus query parameters for generation: use `generate()`.
84+
- Structured generate payload: use `generate_body()`.
85+
- Multipart-form generation: use `generate_multipart()` when the caller explicitly needs that shape.
86+
87+
Key method names:
88+
89+
- `generate`
90+
- `generate_body`
91+
- `generate_multipart`
92+
- `recognize`
93+
- `recognize_base64`
94+
- `recognize_multipart`
95+
- `scan`
96+
- `scan_base64`
97+
- `scan_multipart`
98+
99+
## Non-obvious SDK rules
100+
101+
1. Install `aspose-barcode-cloud`, but import from `aspose_barcode_cloud`.
102+
2. Construct APIs as `GenerateApi(ApiClient(Configuration(...)))` or by reusing a shared `ApiClient`. Passing `Configuration` directly to an API class is the wrong shape for this SDK.
103+
3. `generate()`, `generate_body()`, and `generate_multipart()` return an `ApiResponse`. The image bytes are in `response.data`, not in a model object or file path.
104+
4. Recognize and scan methods return `BarcodeResponseList`. Iterate `result.barcodes` and read `barcode_value`, `type`, `region`, and `checksum`.
105+
5. `recognize_base64()` and `scan_base64()` expect a base64 string in the request model. The SDK does not call `base64.b64encode()` for you.
106+
6. `recognize()` and `recognize_multipart()` take one `DecodeBarcodeType`, but `RecognizeBase64Request.barcode_types` accepts a list.
107+
7. `ScanApi` auto-detects barcode types and does not take a barcode-type filter or the recognition tuning parameters exposed by `RecognizeApi`.
108+
8. GET-based recognize and scan methods only work with remote files reachable by URL. For local files, use multipart or base64.
109+
9. `ApiClient` supports header override through `header_name` and `header_value`; tests use this to customize `x-aspose-client`.
110+
10. Set `config.debug = True` when you need SDK and `urllib3` request logging.
111+
112+
## Common patterns
113+
114+
Generate and save a QR code:
115+
116+
```python
117+
from aspose_barcode_cloud import (
118+
ApiClient,
119+
CodeLocation,
120+
Configuration,
121+
EncodeBarcodeType,
122+
GenerateApi,
123+
)
124+
125+
config = Configuration(client_id=client_id, client_secret=client_secret)
126+
api = GenerateApi(ApiClient(config))
127+
128+
response = api.generate(
129+
EncodeBarcodeType.QR,
130+
"hello from Python",
131+
text_location=CodeLocation.NONE,
132+
)
133+
134+
with open("qr.png", "wb") as fh:
135+
fh.write(response.data)
136+
```
137+
138+
Recognize a local file stream:
139+
140+
```python
141+
from aspose_barcode_cloud import ApiClient, Configuration, DecodeBarcodeType, RecognizeApi
142+
143+
config = Configuration(client_id=client_id, client_secret=client_secret)
144+
api = RecognizeApi(ApiClient(config))
145+
146+
with open("qr.png", "rb") as fh:
147+
result = api.recognize_multipart(DecodeBarcodeType.QR, fh)
148+
149+
for barcode in result.barcodes:
150+
print(barcode.barcode_value)
151+
```
152+
153+
Auto-scan bytes already in memory:
154+
155+
```python
156+
import base64
157+
158+
from aspose_barcode_cloud import ApiClient, Configuration, ScanApi, ScanBase64Request
159+
160+
config = Configuration(client_id=client_id, client_secret=client_secret)
161+
api = ScanApi(ApiClient(config))
162+
163+
with open("unknown.png", "rb") as fh:
164+
payload = base64.b64encode(fh.read()).decode("utf-8")
165+
166+
result = api.scan_base64(ScanBase64Request(file_base64=payload))
167+
```
168+
169+
## Working in this repo
170+
171+
Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, package metadata, or generated code in `submodules/python`.
172+
173+
Read `references/snippet-map.md` when the task needs example code, README-aligned snippets, or the closest existing pattern for generate, recognize, or scan scenarios.
174+
175+
## Final checklist
176+
177+
1. Use the correct package and import pair: `aspose-barcode-cloud` for install, `aspose_barcode_cloud` for imports.
178+
2. Build API classes from `ApiClient(Configuration(...))`.
179+
3. Choose GET only for public URLs, multipart for local files, and base64 request models for bytes already in memory.
180+
4. Base64-encode request payloads yourself before calling `recognize_base64()` or `scan_base64()`.
181+
5. Treat generate responses as `response.data` bytes and recognize/scan responses as `result.barcodes`.
182+
6. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`.

‎skills/aspose-barcode-cloud-python/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Aspose.BarCode Cloud Python"
3+
short_description: "Write Python barcode code with Aspose Cloud"
4+
default_prompt: "Use $aspose-barcode-cloud-python to write or update Python code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud."

‎skills/aspose-barcode-cloud-python/references/repo-workflow.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Python submodule workflow
2+
3+
Use this reference when the task edits SDK source, tests, snippets, package metadata, or generated files inside `submodules/python`.
4+
5+
## Layout
6+
7+
- `aspose_barcode_cloud/api`: generated API clients such as `generate_api.py`, `recognize_api.py`, and `scan_api.py`.
8+
- `aspose_barcode_cloud/models`: generated request and response models plus enums.
9+
- `aspose_barcode_cloud/configuration.py`, `api_client.py`, `rest.py`, and `exceptions.py`: auth, HTTP transport, and runtime behavior.
10+
- `docs`: generated endpoint and model docs.
11+
- `tests`: unittest coverage for configuration, auth, headers, generate, recognize, scan, exceptions, and end-to-end flows.
12+
- `snippets`: runnable documentation snippets grouped by generate/read scenario.
13+
- `scripts`: snippet runners and post-generation helpers such as example insertion and deprecation-warning injection.
14+
- `README.md` and `example.py`: user-facing usage examples.
15+
16+
## Validation
17+
18+
On Windows, run repo scripts and Make targets through WSL.
19+
20+
From `submodules/python`:
21+
22+
- `make init` or `make venv` to install dependencies.
23+
- `make format`
24+
- `make lint`
25+
- `make test`
26+
- `make test-example`
27+
- `make test-tox`
28+
29+
`make test` does more than unit tests:
30+
31+
- runs `pytest --cov=aspose_barcode_cloud tests/`
32+
- runs `./scripts/run_snippets.sh`
33+
34+
`run_snippets.sh` creates `snippets_test`, symlinks the local `aspose_barcode_cloud` package into it, injects credentials into each snippet, and executes every snippet. Treat snippet failures as consumer-facing regressions, not just sample breakage.
35+
36+
`make after-gen` is the post-processing pipeline used by code generation. It runs:
37+
38+
- `make format`
39+
- `make insert-examples`
40+
- `make add-warnings`
41+
- `make format_doc`
42+
43+
## Test configuration
44+
45+
- Tests load `tests/configuration.json` first and then fall back to `TEST_CONFIGURATION_*` environment variables.
46+
- `tests/load_configuration.py` maps constructor parameter names from `Configuration.__init__` directly to env vars.
47+
- Useful names include `TEST_CONFIGURATION_CLIENT_ID`, `TEST_CONFIGURATION_CLIENT_SECRET`, `TEST_CONFIGURATION_ACCESS_TOKEN`, `TEST_CONFIGURATION_HOST`, and `TEST_CONFIGURATION_TOKEN_URL`.
48+
- `tests/configuration.example.json` still shows an older v3.0 host, but `Configuration` defaults to `https://api.aspose.cloud/v4.0`. Match the surrounding file when editing repo code and prefer the runtime default for new examples.
49+
50+
## Regenerated code workflow
51+
52+
If you change generated SDK code in this mono-repo:
53+
54+
1. Make the intended SDK edit in `submodules/python` so the target behavior is clear.
55+
2. Mirror the change in the matching template under `codegen/Templates/python` when the file is generated.
56+
3. Stage the Python submodule changes.
57+
4. From the repo root, run `make python` through WSL.
58+
5. Ensure `submodules/python` has no new unstaged diffs after regeneration.
59+
6. If regeneration reintroduces old code, keep fixing templates or post-generation helpers until the generated output matches the intended SDK change.
60+
61+
## Useful anchors
62+
63+
- `aspose_barcode_cloud/__init__.py`: public exports from the package.
64+
- `tests/load_configuration.py`: how test config is discovered.
65+
- `tests/test_generate_and_recognize.py`: end-to-end generate then recognize flow.
66+
- `scripts/run_snippets.sh` and `scripts/run_snippet.sh`: snippet harness.
67+
- `Makefile`: local validation and post-generation entry points.

‎skills/aspose-barcode-cloud-python/references/snippet-map.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Snippet and example map
2+
3+
Use this reference when you want the closest existing Python pattern before writing new SDK code or when updating docs, snippets, and examples.
4+
5+
## Small end-user examples
6+
7+
- `example.py`: compact generate-then-recognize flow using `ApiClient(Configuration(...))`.
8+
- `snippets/manual_fetch_token.py`: manual OAuth client-credentials token fetch without using the SDK.
9+
10+
## Generate patterns
11+
12+
- `snippets/generate/save/generate_get.py`: simple `generate()` and save-to-file flow.
13+
- `snippets/generate/save/generate_body.py`: `generate_body()` with `GenerateParams`.
14+
- `snippets/generate/save/generate_multipart.py`: multipart generation flow.
15+
- `snippets/generate/set_text/*`: `EncodeData` and `EncodeDataType` examples.
16+
- `snippets/generate/set_size/*`: width, height, resolution, and units examples.
17+
- `snippets/generate/set_colorscheme/*`: foreground and background color examples.
18+
- `snippets/generate/appearance/*`: richer `BarcodeImageParams` examples.
19+
20+
## Recognize and scan patterns
21+
22+
- `snippets/read/set_source/recognize_get.py`: recognize from a public URL.
23+
- `snippets/read/set_source/recognize_multipart.py`: recognize from a local file stream.
24+
- `snippets/read/set_source/recognize_body.py`: recognize from base64 bytes.
25+
- `snippets/read/set_source/scan_get.py`: auto-scan from a public URL.
26+
- `snippets/read/set_source/scan_multipart.py`: auto-scan from a local file stream.
27+
- `snippets/read/set_source/scan_body.py`: auto-scan from base64 bytes.
28+
- `snippets/read/set_target_types/*`: choosing a single `DecodeBarcodeType` or a list for `RecognizeBase64Request.barcode_types`.
29+
- `snippets/read/set_quality/*`: `RecognitionMode` examples.
30+
- `snippets/read/set_image_kind/*`: `RecognitionImageKind` examples.
31+
32+
## Tests worth copying
33+
34+
- `tests/test_generate_and_recognize.py`: generate a barcode, save it locally, and recognize it end to end.
35+
- `tests/test_generate_api.py`: generate via GET, body, and multipart variants.
36+
- `tests/test_recognize_api.py`: recognize via base64 body, multipart, and public URL.
37+
- `tests/test_scan_api.py`: scan via base64 body, multipart, and public URL.
38+
- `tests/test_auth.py`: client credential flow, external token flow, and unauthorized failures.
39+
- `tests/test_headers.py`: custom `ApiClient` header override behavior.
40+
- `tests/test_exception.py`: error and exception behavior.
41+
- `tests/test_load_configuration.py`: config-file and environment loading behavior.

0 commit comments

Comments
 (0)