Skip to content

Commit 0a265ae

Browse files
ivankamkinivankamkin
authored
Add skill for AI Agent (#104)
* Add skill * Add AI agent skill section to README * Rename Python skill to generate-and-scan-barcode
1 parent f732094 commit 0a265ae

5 files changed

Lines changed: 298 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ To use these SDKs, you will need Client Id and Client Secret which can be looked
3434

3535
The complete source code is available in this repository folder. You can either directly use it in your project via source code or get [from PyPi](https://pypi.org/project/aspose-barcode-cloud/) (recommended).
3636

37+
## AI Agent Skills
38+
39+
This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-python/SKILL.md`](skills/generate-and-scan-barcode-python/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns.
40+
3741
## Prerequisites
3842

3943
To use Aspose.BarCode Cloud SDK for Python you need to register an account with [Aspose Cloud](https://www.aspose.cloud) and lookup/create Client Secret and Client Id at [Cloud Dashboard](https://dashboard.aspose.cloud/applications). There is free quota available. For more details, see [Aspose Cloud Pricing](https://purchase.aspose.cloud/).
@@ -146,4 +150,3 @@ Class | Method | HTTP request | Description
146150
- [RegionPoint](docs/RegionPoint.md)
147151
- [ScanBase64Request](docs/ScanBase64Request.md)
148152

149-

‎skills/generate-and-scan-barcode-python/SKILL.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
name: generate-and-scan-barcode-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+
# Generate and scan barcode in 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/generate-and-scan-barcode-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: "Generate and scan barcode in Python"
3+
short_description: "Use Aspose.BarCode Cloud from Python"
4+
default_prompt: "Use $generate-and-scan-barcode-python to write or update Python code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud."

‎skills/generate-and-scan-barcode-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/generate-and-scan-barcode-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)