Skip to content

docs: README accuracy and structure pass - #16

Closed
embeddinglayer wants to merge 1 commit into
mainfrom
docs/readme-polish
Closed

embeddinglayer wants to merge 1 commit into
mainfrom
docs/readme-polish

Conversation

@embeddinglayer

Copy link
Copy Markdown
Contributor

Brings the README in line with the section order shared by the other SDK READMEs and checks it against the source. Only README.md changes; existing wording is kept wherever it was already correct.

Structure

  • Sections reordered and renamed: Installation, Quick start, Authentication (merges "API Keys" and "Authentication"), IP and domain lookups, Account, Feeds (method list and scope table, with Streaming, Exports and Downloads as subsections), Asyncio and Trio, Errors, Retries and timeouts, Configuration (Server URL and Custom HTTP client as subsections), Response metadata (was "Debugging"), gRPC schema, Requirements, Versioning (was "Maturity"), Documentation, Contributions, License.
  • The "Available Resources and Operations" list of client methods is folded into the sections that show each method; the feed method list and table moved to Feeds unchanged.
  • Table of contents rebuilt; the "Development" top-level heading is gone.

Added (each checked against src/synthient)

  • Quick start: one complete program.
  • Lookups: lookup_ip accepts ipaddress objects and rejects invalid input before a request; empty and oversized batches; lookup_domain limit range and default, and the "inactive" result (_base.py, _client.py).
  • Account: lookup_quota.resets_in, and a health() example.
  • Exports: list_exports limit range and default.
  • Asyncio and Trio: an async stream example.
  • Retries: backoff from about one second up to 30 seconds, never shorter than Retry-After, and no retry when Retry-After exceeds a minute (_retry.py).
  • Timeouts: a timeout raises APITimeoutError, except while reading a download() body.
  • Configuration: a table of every constructor argument with its default; synthient.__version__ and the User-Agent prefix.
  • Response metadata: the hook also sees error responses but not storage downloads; rate limit headers are read from headers.
  • gRPC schema: the endpoint, plaintext, symbols and timeout arguments of fetch() (grpcschema.py).
  • Links from each section to the matching page on docs.synthient.com.

Not verified from this repository

  • The ja4t row of the feed table is left exactly as it was. Its scope names (JA4T_STREAM, JA4T_FEED) do not appear in .sdkgen/openapi.json, unlike every other scope in the table.
  • "Hourly exports roll into the daily export shortly after 00:30 UTC" and the 400 for a rolled-up hour are server behaviour and were left as written.

Copilot AI balanced review requested due to automatic review settings November 15, 2026 22:31

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

The change still needs updates because the README’s exception documentation is inaccurate and overly broad, omitting that invalid input types can raise TypeError/AttributeError (not just ValueError), which could mislead users.

2 open issues
What changed in this PR

Updates the repository README for accuracy and consistency with the standardized SDK README structure while aligning examples and behavioral notes with the current Python SDK.

Changes:

  • Reorganized and renamed sections, rebuilt the table of contents, and consolidated method listings into relevant sections.
  • Added/updated examples and documented behavior for lookups, feeds/exports/downloads, async usage, retries/timeouts, configuration, response metadata, and gRPC schema.
  • Added deep links from each section to the corresponding docs.synthient.com pages.
File Description
README.md Restructures the README and refreshes examples and behavior documentation to match the current SDK surface area and standardized README layout.

Review effort: Balanced

Comment thread README.md
```

`network`, `location`, and `intelligence` are `None` when the API has no data for them. A client pools connections and is safe to share across threads, so reuse one and close it with `close()` or a `with` block. The examples below reuse an open `client`, and runnable programs are in [examples](https://github.com/synthient/synthient-python/tree/main/examples).
`network`, `location`, and `intelligence` are `None` when the API has no data for them. An invalid address raises `ValueError` before any request is sent, and a private or reserved address raises an `APIError` with status 422.
Comment thread README.md
| `user_agent` | `None` | A product token appended to the `User-Agent` header |
| `response_hook` | `None` | Called with the [metadata](#response-metadata) of every API response |

An invalid argument raises `ValueError` when the client is created, and an API key that is not a string raises `TypeError`.
@embeddinglayer
embeddinglayer deleted the docs/readme-polish branch November 15, 2026 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants