v0.3.0

[codefitz]

This pull request updates the Tideway Python library and its documentation to remove deprecated helper function aliases, route all API calls through the main REST wrappers, and refreshes documentation to match the new, leaner API surface. It also updates documentation and examples to reflect support for newer BMC Discovery API versions (up to 1.16), and removes all references to deprecated function names in both user guides and endpoint documentation.

The most important changes are:

Deprecation and API Surface Cleanup

• Removed all deprecated helper function aliases from documentation and examples, consolidating API usage around the top-level REST wrappers (e.g., api_about, get_admin_licensing) and eliminating references to old methods like .about(), .licensing(), .baseline(), .graphNode(), etc. [1]], [2]], [3]], [4]], [5]], [6]], [7]])

Documentation and Example Updates

• Updated all code examples in README.md, docs/index.md, and quickstart/response guides to use the new, non-deprecated API calls (e.g., tw.api_about instead of tw.about()). [1]], [2]], [3]], [4]])
• Added a reference to a new example notebook for admin API usage in the documentation. [1]], [2]])

API Version Support

• Updated documentation to state support for BMC Discovery API versions up to 1.16, and changed the default api_version parameter in quickstart guides accordingly. [1]], [2]], [3]])

Release Notes

• Added release notes for version 0.3.0, highlighting the removal of deprecated helpers and the streamlined API interface. [1]], [2]])

Development Guidelines

• Added an AGENTS file outlining development standards for API helper usage, payload handling, style, safety, and validation for contributors. ([AGENTSR1-R17])

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67ee438e3b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR refactors the Tideway client to route module-level helpers through the central Appliance REST wrappers, removes deprecated helper aliases from code/docs, updates default and documented API version support to 1.16, and adds a set of example notebooks plus contributor guidance.

Changes:

• Updated core client plumbing (Appliance HTTP methods and discoRequests) so all feature modules use the top-level REST wrappers, including support for custom response content types and multipart uploads.
• Removed deprecated helper aliases across modules and aligned docs and examples (README, MkDocs, notebooks) to the “lean” API surface centered on tw.api_about and Appliance.get/post/patch/put/delete.
• Added a suite of example notebooks for admin, data, discovery, topology, taxonomy, models, events/knowledge, and credentials APIs, plus an AGENTS file documenting development standards.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
tideway/vault.py	Routes vault helpers (get_vault, patch_vault) through self.get/self.patch and removes deprecated aliases.
tideway/topology.py	Switches topology helpers to use self.get/post/patch/put and replaces the old visualization property alias with an explicit get_topology_viz_state method.
tideway/taxonomy.py	Replaces direct discoRequests usage with self.get for taxonomy section/locale/nodekind/relkind helpers.
tideway/security.py	Refactors security (LDAP, groups, permissions, users, tokens) helpers to use the Appliance REST wrappers.
tideway/models.py	Routes all models CRUD/topology/node helpers via self.get/post/patch/delete for consistency with other modules.
tideway/main.py	Updates default api_version to "1.16", extends Appliance.get/post/patch/put/delete to accept response, files, and data, exposes API admin helpers (api_about, api_swagger, api_schema, api_paths, api_help, get_admin_*) and removes deprecated top-level admin aliases.
tideway/knowledge.py	Switches knowledge state/status endpoints to self.get and rewrites post_knowledge to use Appliance.post with multipart file upload.
tideway/kerberos.py	Refactors Kerberos endpoints to use self.get/post/patch/delete and inlines multipart upload handling for keytabs and ccaches via the new Appliance.post signature.
tideway/events.py	Simplifies events posting to use self.post and removes deprecated status() alias.
tideway/discovery.py	Replaces all direct discoRequests calls with self.get/post/patch/delete across discovery status, excludes, runs, schedules, outposts, and related helpers.
tideway/discoRequests.py	Generalizes discoPost to support JSON, form data, and files, adds docstrings, and makes file/keytab helpers delegate to discoPost while centralizing response/param handling.
tideway/data.py	Refactors search, conditions, nodes, kinds, partitions, import/write, external consumers, and value endpoints to use self.get/post, and removes deprecated aliases; maintains internal pagination helpers.
tideway/credentials.py	Updates credential-type and credential CRUD helpers to use self.get/post/patch/put/delete while keeping higher-level semantic helpers (listCredentialTypes, newCredential, etc.).
tideway/admin.py	Replaces older admin helpers (baseline, admin, licensing) with explicit get_admin_* methods for baseline, about, licensing, instance, cluster, organizations, preferences, reports, and SMTP, all via self.get.
setup.py	Bumps package version to 0.3.0 and adds tabulate as a dependency (used in tideway/endpoints.py).
notebooks/topology_api.ipynb	New examples comparing topology helpers (post_topology_nodes, post_topology_nodes_kinds, get_topology_viz_state, etc.) with direct get/post calls.
notebooks/taxonomy_api.ipynb	New examples for taxonomy sections, locales, node kinds, fieldlists, and relationship kinds using both helpers and direct requests.
notebooks/models_api.ipynb	New examples for model listing, CRUD, bulk operations, and topology/node queries by key or node id, demonstrating helper vs direct usage.
notebooks/events_knowledge_api.ipynb	New examples for posting events and interacting with knowledge endpoints (state, status, uploads, trigger patterns); includes a bug where get_knowledge_trigger_patterns is called as a function instead of used as a property.
notebooks/discovery_api.ipynb	New discovery notebook showcasing helpers vs direct calls for status, providers, excludes, runs, results, schedules, and outposts.
notebooks/data_api.ipynb	New data notebook for /data/search, bulk search, conditions, node lookups/graphs, kinds, partitions, candidates, and external consumers via tideway.data.
notebooks/credentials_api.ipynb	New raw-REST notebook for vault credential types and credentials; contains a bug where cred_id is used before being defined if the “get by id” cell is run first.
notebooks/admin_consolidation.ipynb	New notebook with raw admin and consolidation examples using tw.get/tw.post directly.
notebooks/admin_api.ipynb	New admin API examples built around tw.get and the admin endpoints plus api_swagger, api_schema, api_paths, and api_help.
docs/quickstart/responses.md	Updates quickstart examples to use tw.api_about instead of the deprecated .about() helper while keeping the responses walk-through current.
docs/quickstart/initiation.md	Updates the documented default api_version to "1.16" and notes Discovery 25.x API support.
docs/index.md	Aligns examples with tw.api_about, extends documented API version support to 1.16, and adds a link to an admin example notebook (currently pointing at a non-existent filename).
docs/endpoints/topology.md	Removes deprecated topology helper sections (graphNode, getNodes, getNodeKinds, visualizationState, updateVizState, replaceVizState) and standardizes on the new helper names.
docs/endpoints/data.md	Updates get_data_partitions description and removes documentation for deprecated data helpers (searchQuery, nodeLookup, lookupNodeKind, graphNode, partitions, best_candidate, top_candidates, twImport, twWrite).
docs/endpoints/appliance.md	Removes documentation for deprecated about, admin, swagger, baseline, and licensing helpers in favor of the api_* and get_admin_* interfaces.
docs/endpoints/admin.md	Rewrites licensing sections to describe get_admin_licensing, get_admin_licensing_csv, and get_admin_licensing_raw, instead of the old licensing() helper.
README.md	Updates examples to use tw.api_about, documents support for API v1.0–1.16, and adds a link to an admin notebook that currently references admin_api_examples.ipynb instead of the actual file name.
AGENTS	New contributor guidance defining how to use Appliance wrappers, handle uploads and content types, and validate changes in this repo.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The example notebook link points to notebooks/admin_api_examples.ipynb, but the repository only contains notebooks/admin_api.ipynb, so this URL will 404 for users trying to download the example. Update the link and filename to match the actual notebook path.

Suggested change

	- Example notebook: [`notebooks/admin_api_examples.ipynb`](https://github.com/traversys/Tideway/blob/main/notebooks/admin_api_examples.ipynb) (download via `curl -O https://raw.githubusercontent.com/traversys/Tideway/main/notebooks/admin_api_examples.ipynb`)
	- Example notebook: [`notebooks/admin_api.ipynb`](https://github.com/traversys/Tideway/blob/main/notebooks/admin_api.ipynb) (download via `curl -O https://raw.githubusercontent.com/traversys/Tideway/main/notebooks/admin_api.ipynb`)

[Copilot]

The example notebook link refers to notebooks/admin_api_examples.ipynb, but the actual file in the repository is notebooks/admin_api.ipynb, so this link will be broken. Update the displayed path and GitHub/raw URLs to point at the correct notebook name.

Suggested change

	Example notebook: [`notebooks/admin_api_examples.ipynb`](https://github.com/traversys/Tideway/blob/main/notebooks/admin_api_examples.ipynb) (download via `curl -O https://raw.githubusercontent.com/traversys/Tideway/main/notebooks/admin_api_examples.ipynb`)
	Example notebook: [`notebooks/admin_api.ipynb`](https://github.com/traversys/Tideway/blob/main/notebooks/admin_api.ipynb) (download via `curl -O https://raw.githubusercontent.com/traversys/Tideway/main/notebooks/admin_api.ipynb`)

[Copilot]

get_knowledge_trigger_patterns is defined as a property on Knowledge, but this notebook cell calls it like a function with parameters, which will raise a TypeError because the property returns a Response object, not a callable. Either switch this to call the underlying getKnowledgeTriggerPatterns(lookup_data_sources=...) method or change the API to expose a callable get_knowledge_trigger_patterns(...) method instead of a property.

[Copilot]

This cell references cred_id in the if cred_id: guard before cred_id is defined anywhere, which will raise a NameError if a user runs this cell before the "Create a credential" cell. Either initialize cred_id = None in the setup cell or move the "Get a credential by id" cell after the cell that creates and sets cred_id.

[Copilot]

Normal methods should have at least one parameter (the first of which should be 'self').

Suggested change

	@staticmethod

[Copilot]

This taxonomy API notebook turns off TLS certificate verification by setting SSL_VERIFY = False and passing it to tideway.appliance, causing all HTTPS requests to accept any server certificate. A network-positioned attacker could impersonate the Discovery appliance and tamper with or exfiltrate taxonomy metadata. Make certificate verification the default (e.g., SSL_VERIFY/ssl_verify set to True with a proper CA bundle) and restrict ssl_verify=False to short-lived, local testing.

Suggested change

	"SSL_VERIFY = False # set to True when using valid certs\n",
	"SSL_VERIFY = True # enable TLS verification by default; set to a CA bundle path if needed\n",

[Copilot]

This topology API notebook disables TLS certificate verification via SSL_VERIFY = False passed into tideway.appliance, so all HTTPS calls to topology endpoints will trust any server certificate. An attacker with network access can man-in-the-middle these calls, intercepting or modifying graph and topology data returned from the appliance. Enable certificate verification by default (set SSL_VERIFY/ssl_verify to True and use a trusted CA bundle) and only allow ssl_verify=False in tightly controlled development scenarios.

Suggested change

	"SSL_VERIFY = False # set to True when using valid certs\n",
	"SSL_VERIFY = True # set to False *only* for tightly controlled dev with self-signed certs\n",

[Copilot]

This data API example turns off TLS certificate verification via SSL_VERIFY = False passed into tideway.appliance, causing all HTTPS requests to the Discovery data endpoints to trust any certificate. A man-in-the-middle on the network could spoof the appliance, capture search queries and results, or inject modified data into responses. Enable certificate verification by default (e.g., SSL_VERIFY/ssl_verify set to True with a trusted CA bundle) and use ssl_verify=False only for short-lived, local testing.

Suggested change

	"SSL_VERIFY = False # set to True when using valid certs\n",
	"SSL_VERIFY = True # set to False only for short-lived, local testing\n",

[Copilot]

This events & knowledge notebook disables TLS certificate verification via SSL_VERIFY = False passed into tideway.appliance, which forces all HTTPS calls to trust any certificate. An attacker on the network could spoof the Discovery appliance, intercepting events and knowledge uploads or injecting malicious content into responses. Enable certificate verification by default (set SSL_VERIFY/ssl_verify to True with a trusted CA) and reserve disabling verification for exceptional, local-only testing.

Suggested change

	"SSL_VERIFY = False # set to True when using valid certs\n",
	"SSL_VERIFY = True # verify TLS certs by default; set to False only for local testing with self-signed certs\n",

[Copilot]

This initiation guide documents ssl_verify with a default of False and recommends leaving it at that value for self-signed HTTPS, which means the client will skip TLS certificate validation by default. A network attacker can exploit this to present a forged certificate, transparently intercepting or altering all API traffic from the Tideway client. Change the default and guidance so certificate verification is enabled by default (e.g., ssl_verify=True with a trusted CA bundle) and reserve ssl_verify=False for exceptional, short-lived testing only.

Suggested change

	| ssl_verify | | Boolean | False | Choose whether to query the API using a valid SSL certificate. If you are using self-signed HTTPS then you should leave this with the default value.
	| ssl_verify | | Boolean | True | Choose whether to verify the API's HTTPS certificate against a trusted CA bundle. For self-signed HTTPS, prefer configuring a trusted CA/certificate; only set this to `False` for exceptional, short-lived testing.