Skip to content

v0.3.0 #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
codefitz wants to merge 9 commits into
base: main
Choose a base branch
from
Open

v0.3.0 #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4469114
Refactor API helpers to use Appliance methods
codefitz Dec 9, 2025
ab084eb
Add tabulate to install_requires (#35)
Copilot Dec 9, 2025
bfcdd4e
Remove deprecated helper functions and update docs
codefitz Dec 9, 2025
f49dc30
Update API version support to 1.16 and add admin API notebook
codefitz Dec 9, 2025
afcc905
Update admin API example notebook and docs
codefitz Dec 9, 2025
7b20758
Add admin consolidation notebook and update API examples
codefitz Dec 9, 2025
ab38e3f
Rename admin API notebook for clarity
codefitz Dec 9, 2025
9bd079c
Add Tideway Credentials API example notebook
codefitz Dec 9, 2025
67ee438
Add example notebooks for Tideway REST APIs
codefitz Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions AGENTS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
Repository: Tideway (BMC Discovery API client)

Mission
- Add or adjust API helpers using the top-level REST wrappers in `tideway/main.py` (`Appliance.get/post/patch/put/delete`). Do not call `requests` or `discoRequests` directly from feature modules, except the explicit non-standard schema endpoints (`/about`, swagger/openapi) which are intentionally direct in `main.py`.
- Preserve parameter handling: set `self.params[...]` before calling a wrapper; the appliance layer resets params after each request.
- Maintain existing deprecation warnings; when adding aliases, warn with `DeprecationWarning` and point to the preferred helper.

Uploads and special payloads
- Use `Appliance.post(..., files=..., content_type=...)` for multipart uploads (TKU/knowledge, Kerberos keytabs/ccaches). Do not reintroduce `discoRequests` helpers in new code.
- When a response needs a specific MIME type (e.g., licensing CSV/raw), pass `response="application/zip"` or similar via the wrapper.

Style and safety
- Keep code ASCII-only unless the file already uses Unicode. Keep comments minimal and clarifying, not redundant.
- Do not remove or overwrite user changes; avoid destructive git commands.

Validation
- Preferred quick check: `python3 -m compileall tideway`.
15 changes: 9 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ Simplified Python library for BMC Discovery API Interface that makes use of the
```python
>>> import tideway
>>> tw = tideway.appliance('appliance-hostname','auth-token')
>>> tw.about().url
>>> tw.api_about.url
'https://appliance-hostname/api/about'
>>> tw.about().status_code
>>> tw.api_about.status_code
200
>>> tw.about().text
>>> tw.api_about.text
{
"api_versions": [
"1.0","1.1","1.2","1.3","1.4","1.5","1.6","1.7","1.8","1.9","1.10","1.11","1.12","1.13","1.14"
"1.0","1.1","1.2","1.3","1.4","1.5","1.6","1.7","1.8","1.9","1.10","1.11","1.12","1.13","1.14","1.15","1.16"
],
"component": "REST API",
"version":"DaaS",
Expand All @@ -30,6 +30,8 @@ Tideway removes the extra layer of manually constructing a URL and parameters fo

Documentation can be found at [https://traversys.github.io/Tideway/](https://traversys.github.io/Tideway/).

- 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`)
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

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

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 uses AI. Check for mistakes.

## Installation

- Tideway can be installed via PyPI:
Expand All @@ -38,7 +40,7 @@ Documentation can be found at [https://traversys.github.io/Tideway/](https://tra
$ python -m pip install tideway
```

- Tideway supports BMC Discovery 11.3+, API v1.0-1.14 using Python 3.
- Tideway supports BMC Discovery 11.3+, API v1.0-1.16 using Python 3.

## Releases

Expand All @@ -50,4 +52,5 @@ $ python -m pip install tideway
| 0.1.4 | Search bulk update | Discovery 12.3 (21.3) enforces strict case for "Bearer" header - api calls will not current work. | Now includes headers for non-formatted search. |
| 0.1.5 | Updated to support Discovery 12.3 (API version 1.3) | - Missing 'complete' parameter option on graphNode() function. | - Fixed issue with Bearer capitalisation.<br>- Search Bulk will now return the full response on failure |
| 0.2.0 | Updated to include Kerberos, Models and Taxonomy endpoints.<br><br>Added new high level generic endpoint function calls<br><br>Refactored function names/decorators to match API endpoints as close as possible.<br><br>Supports Discovery 22.2 (12.5) (API version 1.5) and Outpost API version 1.0 | Project missing tkinter module: https://github.com/traversys/Tideway/issues/15 | Added 'complete' parameter to `get_data_nodes_graph()` (replaces `graphNode()`) |
| 0.2.1 | Added `complete` flag for graph calls, bug fixes to pagination and default focus.<br><br>Can retrieve condition templates without an ID.<br><br>Kerberos realm detection fixed and parameters are reset after each request.<br><br>Removed unused Tkinter library.<br><br>Updated to support API version 1.14 | May not work with all new endpoints. | | Issue: https://github.com/traversys/Tideway/issues/15 |
| 0.2.1 | Added `complete` flag for graph calls, bug fixes to pagination and default focus.<br><br>Can retrieve condition templates without an ID.<br><br>Kerberos realm detection fixed and parameters are reset after each request.<br><br>Removed unused Tkinter library.<br><br>Updated to support API version 1.14 | May not work with all new endpoints. | | Issue: https://github.com/traversys/Tideway/issues/15 |
| 0.3.0 | Removed deprecated helper aliases and routed all modules through the top-level REST wrappers.<br><br>Documentation refreshed to reflect the lean API surface. | | Deprecated helper functions removed; docs and examples updated. |
43 changes: 16 additions & 27 deletions docs/endpoints/admin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,45 +52,34 @@ Example:
{'api_versions': ['1.0', '1.1', '1.2'], 'component': 'REST API', 'product': 'BMC Discovery', 'version': '12.2'}
```

## baseline()
## get_admin_licensing

[Deprecated] See [get_admin_baseline](#get_admin_baseline) for usage.
Get the latest signed licensing report (plain text by default).

Syntax: `.baseline()`

## about()

[Deprecated] See [get_admin_about](#get_admin_about) for usage.

Syntax: `.about()`
Syntax:

## licensing()
```
.get_admin_licensing
```

Get the latest signed licensing report.
## get_admin_licensing_csv

- CSV option returns raw license data in CSV format as a zip file for offline analysis.
- RAW option return an encrypted raw license object for import to another appliance.
Get the latest raw license data in CSV format as a zip file for offline analysis.

Syntax:

```
.licensing([ _content_type_ ])
.get_admin_licensing_csv
```

| Parameters | Type | Required | Default Value | Options |
| ------------ | ------ | :------: | ------------- | ------- |
| content_type | String | No | "text/plain" | <ul><li>"text/plain"</li><li>"csv"</li><li>"raw"</li></ul>
## get_admin_licensing_raw

Example:
```python
>>> tw.licensing()
-----BEGIN LICENSE REPORT-----
License report
==============
Get the latest license data as an encrypted raw license object for import to another appliance.

Syntax:

Report start time: 2021-01-18 23:00:00.409987+00:00
Report end time : 2021-01-21 23:00:00.410085+00:00
...
```
.get_admin_licensing_raw
```

## get_admin_instance
Expand Down Expand Up @@ -217,4 +206,4 @@ Example:
{
...
}
```
```
55 changes: 1 addition & 54 deletions docs/endpoints/appliance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,59 +355,6 @@ Example:

```

## about()

[Deprecated] See [api_about](#api_about) for usage.

Syntax: `.about()`

## admin()

[Deprecated] See [get_admin_about](#get_admin_about) for usage.

Syntax: `.admin()`

## swagger()

[Deprecated] See [api_swagger](#api_swagger) for usage.

Syntax: `.swagger()`

## baseline()

[Deprecated] See [get_admin_baseline](#get_admin_baseline) for usage.

Syntax: `.baseline()`

## licensing()

Get the latest signed licensing report.

- CSV option returns raw license data in CSV format as a zip file for offline analysis.
- RAW option return an encrypted raw license object for import to another appliance.

Syntax:

```
.licensing([ _content_type_ ])
```

| Parameters | Type | Required | Default Value | Options |
| ------------ | ------ | :------: | ------------- | ------- |
| content_type | String | No | "text/plain" | <ul><li>"text/plain"</li><li>"csv"</li><li>"raw"</li></ul>

Example:
```python
>>> tw.licensing()
-----BEGIN LICENSE REPORT-----
License report
==============

Report start time: 2021-01-18 23:00:00.409987+00:00
Report end time : 2021-01-21 23:00:00.410085+00:00
...
```

## help()

- Get help on specific Discovery API endpoint and function to use. Outputs full list by default.
Expand All @@ -433,4 +380,4 @@ Endpoint Function Description
/vault/credentials/{cred_id} updateCredential(cred_id, body) Updates partial resources of a credential. Missing properties are left unchanged.
/vault/credentials/{cred_id} replaceCredential(cred_id, body) Replaces a single credential. All required credential properties must be present.

```
```
56 changes: 1 addition & 55 deletions docs/endpoints/data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ Syntax:

## get_data_partitions

Graph data represents a set of nodes and relationships that are associated to the given node.
Get names and IDs of partitions available on the appliance.

Syntax:

Expand All @@ -359,36 +359,6 @@ Example:
}
```

## searchQuery()

[Deprecated] See [search](#search) for usage.

Syntax: `.searchQuery(__json__ [, _offset_ ] [, _results_id_ ] [, _format_ ] [, _limit_ ] [, _delete_ ])`

## nodeLookup()

[Deprecated] See [get_data_nodes](#get_data_nodes) for usage.

Syntax: `.nodeLookup(__node_id__ [, _relationships_ ] [, _traverse_ ] [, _flags_ ])`

## lookupNodeKind()

[Deprecated] See [get_data_kinds](#get_data_kinds) for usage.

Syntax: `.lookupNodeKind(__kind__ [, _offset_ ] [, _results_id_ ] [, _format_ ] [, _limit_ ] [, _delete_ ])`

## graphNode()

[Deprecated] See [get_data_nodes_graph](#get_data_nodes_graph) for usage.

Syntax: `.graphNode(__node_id__ [, _focus_ ] [, _apply_rules_ ]))`

## partitions()

[Deprecated] See [get_data_nodes_graph](#get_data_nodes_graph) for usage.

Syntax: `.partitions()`

## post_data_partitions()

Create a Partition.
Expand Down Expand Up @@ -507,27 +477,3 @@ Syntax:
| ------------- | ------ | :------: | ------------- | ------- |
| consumer_name | String | Yes | N/A | N/A |
| path | String | No | N/A | N/A |

## best_candidate()

[Deprecated] See [post_data_candidate](#post_data_candidate) for usage.

Syntax: `.post_data_candidate(__JSON__)`

## top_candidates()

[Deprecated] See [post_data_candidates](#post_data_candidates) for usage.

Syntax: `.post_data_candidates(__json__)`

## twImport()

[Deprecated] See [post_data_import](#post_data_import) for usage.

Syntax: `.twImport(__json__)`

## twWrite()

[Deprecated] See [post_data_write](#post_data_write) for usage.

Syntax: `.twWrite(__json__)`
37 changes: 0 additions & 37 deletions docs/endpoints/topology.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,24 +65,6 @@ Syntax:
| ------------- | ----------- | :------: | ------------- | -------- |
| json | JSON Object | Yes | N/A | N/A |

## graphNode()

[Deprecated] See [get_data_nodes_graph](#get_data_nodes_graph) for usage.

Syntax: `.graphNode(__node_id__ [, _focus_ ] [, _apply_rules_ ])`

## getNodes()

[Deprecated] See [post_topology_nodes](#post_topology_nodes) for usage.

Syntax: `.getNodes(__json__)`

## getNodeKinds()

[Deprecated] See [post_topology_nodes_kinds](#post_topology_nodes_kinds) for usage.

Syntax: `.getNodeKinds(__json__)`

## get_topology_viz_state

Get the current state of the visualization for the authenticated user.
Expand All @@ -106,7 +88,6 @@ Syntax:
| ------------- | ----------- | :------: | ------------- | -------- |
| json | JSON Object | Yes | N/A | N/A |


## put_topology_viz_state()

Update any or all of the attributes of the current state of the visualization for the authenticated user.
Expand All @@ -119,21 +100,3 @@ put_topology_viz_state(__json__)
| Parameters | Type | Required | Default Value | Options |
| ------------- | ----------- | :------: | ------------- | -------- |
| json | JSON Object | Yes | N/A | N/A |

## visualizationState()

[Deprecated] See [get_topology_viz_state](#get_topology_viz_state) for usage.

Syntax: `.visualizationState()`

## updateVizState()

[Deprecated] See [patch_topology_viz_state](#patch_topology_viz_state) for usage.

Syntax: `.updateVizState(__json__)`

## replaceVizState()

[Deprecated] See [put_topology_viz_state](#put_topology_viz_state) for usage.

Syntax: `.replaceVizState(__json__)`
13 changes: 8 additions & 5 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ Simplified Python library for BMC Discovery API Interface that makes use of the
```python
>>> import tideway
>>> tw = tideway.appliance('appliance-hostname','auth-token')
>>> tw.about().url
>>> tw.api_about.url
'https://appliance-hostname/api/about'
>>> tw.about().status_code
>>> tw.api_about.status_code
200
>>> tw.about().text
>>> tw.api_about.text
{
"api_versions": [
"1.0","1.1","1.2","1.3","1.4","1.5","1.6","1.7","1.8","1.9","1.10","1.11","1.12","1.13","1.14"
"1.0","1.1","1.2","1.3","1.4","1.5","1.6","1.7","1.8","1.9","1.10","1.11","1.12","1.13","1.14","1.15","1.16"
],
"component": "REST API",
"version":"DaaS",
Expand All @@ -26,6 +26,8 @@ Tideway follows BMC Discovery's well-structured and documented REST API which ca

Tideway removes the extra layer of manually constructing a URL and parameters for python requests allowing you to query API supported features of Discovery seamlessly and faster than if you were to navigate via the GUI.

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`)
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

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

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 uses AI. Check for mistakes.

## Installation

- Tideway can be installed via PyPI:
Expand All @@ -34,7 +36,7 @@ Tideway removes the extra layer of manually constructing a URL and parameters fo
$ python -m pip install tideway
```

- Tideway supports BMC Discovery 11.3+, API v1.0-1.14 using Python 3.
- Tideway supports BMC Discovery 11.3+, API v1.0-1.16 using Python 3.

## Contents

Expand All @@ -51,3 +53,4 @@ $ python -m pip install tideway
| 0.1.5 | Updated to support Discovery 12.3 (API version 1.3) | - Missing 'complete' parameter option on graphNode() function. | - Fixed issue with Bearer capitalisation.<br>- Search Bulk will now return the full response on failure |
| 0.2.0 | Updated to include Kerberos, Models and Taxonomy endpoints.<br><br>Added new high level generic endpoint function calls<br><br>Refactored function names/decorators to match API endpoints as close as possible.<br><br>Supports Discovery 22.2 (12.5) (API version 1.5) and Outpost API version 1.0 | Project missing tkinter module: https://github.com/traversys/Tideway/issues/15 | Added 'complete' parameter to `get_data_nodes_graph()` (replaces `graphNode()`) |
| 0.2.1 | Added `complete` flag for graph calls, bug fixes to pagination and default focus.<br><br>Can retrieve condition templates without an ID.<br><br>Kerberos realm detection fixed and parameters are reset after each request.<br><br>Removed unused Tkinter library.<br><br>Updated to support API version 1.14 | May not work with all new endpoints. | | Issue: https://github.com/traversys/Tideway/issues/15 |
| 0.3.0 | Removed deprecated helper aliases and routed all modules through the top-level REST wrappers.<br><br>Documentation refreshed to reflect the lean API surface. | | Deprecated helper functions removed; docs and examples updated. |
4 changes: 2 additions & 2 deletions docs/quickstart/initiation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,5 +32,5 @@ Upon initiation the following parameters can be used:
| - | - | - | - | -
| target | Required | String | | The Hostname, FQDN or IP Address of the Discovery instance.
| token | Required | String | | The authentication token of the API user. It is not necessary to include the "bearer" pre-text.
| api_version | | String | "1.5" | This should be the supported version of the API. Discovery 22.2 supports API versions up to 1.5 (outpost 1.0).
| 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.
| api_version | | String | "1.16" | This should be the supported version of the API. Discovery 25.x supports API versions up to 1.16 (outpost 1.0).
| 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.
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
Loading
Loading