feat: add methods to fix #1

fix: updated exceptions to be a little less generic
mmlange · May 25, 2024 · 544f0cd · 544f0cd
1 parent bdbbbba
commit 544f0cd
Show file tree

Hide file tree

Showing 17 changed files with 566 additions and 47 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.22] - 2024-05-25
+
+### Added
+
+- create_integration, delete_integration, and get_search methods.
+
+### Fixed
+
+- Updated exceptions to be a least a little less generic.
+
+## [1.0.21] - 2024-04-25
+
+### Added
+
+- delete_user, edit_user, get_user, and get_users methods.
+
+### Changed
+
+- Log the first 2,000 characters of return text in debug mode.
+
+
+## [1.0.20] - 2024-04-24
+
+### Changed
+
+- Updates to method documentation to note dependencies on specific Armis cloud versions.
+
+## [1.0.19] - 2024-04-24
+
+### Added
+
+- _httpx_callback_request_raise_4xx_5xx method to be used as a callback method to the httpx.Client contructor.  If we get a 401 from the cloud, this allows us to fetch another authorization token and raise the issue to tenacity to retry.
+- create_boundary and delete_boundary methods.
+
+### Changed
+
+- Begin changes to use the status codes exposed under httpx.codes (e.g. httpx.codes.OK).
+
+## [1.0.18] - 2024-04-23
+
+### Added
+
+- get_sites and get_site methods.
+
+### Removed
+
+- get_boundaries_count method.
+
+## [1.0.17] - 2024-04-23
+
+### Added
+
+- Initial release to the world.
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,13 @@
+Both the original source code and new contributions in this repository are released under the [3-Clause BSD license](https://spdx.org/licenses/BSD-3-Clause.html).
+
+Copyright &copy;2024-present Matthew Lange \<mmlange@gmail.com\>.
+
+# The 3-Clause BSD License
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
@@ -3,11 +3,20 @@
 <p align="center"><strong>armis</strong> <em>- A Python library for interacting with the Armis cloud.</em></p>
 
 <p align="center">
-<a href="https://github.com/mmlange/armis-python/actions">
-    <img src="https://github.com/mmlange/armis-python/actions/workflows/testsuite.yml/badge.svg" alt="Test Suite">
-</a>
+<img src="https://img.shields.io/pypi/l/armis?style=flat-square">
+<img src="https://img.shields.io/pypi/pyversions/armis?style=flat-square">
+<img src="https://img.shields.io/librariesio/release/pypi/armis?style=flat-square">
+<img src="https://img.shields.io/github/last-commit/mmlange/armis-python?style=flat-square">
+<a href="https://github.com/mmlange/armis-python/actions"><img src="https://img.shields.io/github/actions/workflow/status/mmlange/armis-python/testsuite.yml?style=flat-square"></a>
+<a href="https://www.pypi.com/projects/armis/"><img src="https://img.shields.io/pypi/v/armis?style=flat-square&logo=python"></a>
+<a href="https://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square"></a>
+
+
 </p>
 
+
+
+
 **armis** is a Python client library for interacting with the Armis cloud.  It connects using **HTTP/2** by default,
 falling back to **HTTP/1.1** when necessary.  Python 3.8+ is supported.
 
@@ -45,6 +54,25 @@ print(devices)
 [{"id": 15, "ipAddress": "10.1.2.3", "name": "super-pc", "firstSeen": "2019-05-15T13:00:00+00:00"}]
 ```
 
+## Queries
+If you need to execute ASQ beyond what `get_devices` gives you, use `get_search`:
+```python
+activities = armis_object.get_search(
+    asq='in:activity timeFrame:"1 Hours"',
+    fields_wanted=["activityUUID"],
+)
+
+print(activities)
+[
+  {
+    "activityUUID": "abc12345678901234567"
+  },
+  {
+    "activityUUID": "def12345678901234567"
+  }
+]
+```
+
 ## Boundary Operations
 
 Let's get all of the boundaries known to the system:
@@ -103,6 +131,50 @@ print(myimportantcollector)
 {'clusterId': 0, 'collectorNumber': 1234, 'defaultGateway': '10.0.0.1', 'httpsProxyRedacted': '', 'ipAddress': '10.0.0.2', 'lastSeen': '2019-05-15T13:00:00+00:00', 'macAddress': '00:12:34:56:78:90', 'name': 'Collector 1234', 'status': 'Offline', 'subnet': '10.0.0.0/24', 'type': 'Physical'}
 ```
 
+## Integration Operations
+Get a list of integrations:
+
+```python
+integrations = a.get_integrations()
+print(integrations)
+[{"changeTime":1715778000000,"collectorId":1234,"creationTime":1715778000000,"currentState":null,"enforcementLists":[],"id":20,"instance":"SPAN eno5","integrationState":"ACTIVE","lastRunEnd":null,"name":"SPAN/TAP","params":{"sniff_interface":"eno5"}},{"changeTime":1715778000000,"collectorId":1234,"creationTime":1715778000000,"currentState":null,"enforcementLists":[],"id":21,"instance":"SPAN eno6","integrationState":"ACTIVE","lastRunEnd":null,"name":"SPAN/TAP","params":{"sniff_interface":"eno6"}}]
+
+```
+
+Get the details for a specific integration:
+
+```python
+integration = a.get_integration(20)
+print(integration)
+
+{"changeTime":1715778000000,"collectorId":1234,"creationTime":1715778000000,"currentState":null,"enforcementLists":[],"id":20,"instance":"SPAN eno5","integrationState":"ACTIVE","lastRunEnd":null,"name":"SPAN/TAP","params":{"sniff_interface":"eno5"},"statistics":null}
+
+```
+
+Create an integration:
+
+```python
+newintegration = a.create_integration(
+    collector_id=20,
+    integration_name="collector 20 capture on eno6",
+    integration_type="SWITCH",
+    integration_params={"sniff_interface": "eno5"}
+)
+
+print(newintegration)
+{"data":{"changeTime":1715778000000,"collectorId":20,"creationTime":1715778000000,"currentState":null,"enforcementLists":[],"id":1234,"instance":"collector 20 capture on eno6","integrationState":"ACTIVE","lastRunEnd":null,"name":"SPAN/TAP","params":{"sniff_interface":"eno6"},"statistics":null},"success":true}
+```
+
+Delete an integration:
+
+```python
+result = a.delete_integration(20)
+print(result)
+{'success': True}
+
+```
+
+
 ## User Operations
 Get a list of users:
 ```python

diff --git a/pyproject.toml b/pyproject.toml
@@ -14,7 +14,8 @@ dynamic = [
 description = "Connect and perform actions with the Armis cloud"
 readme = "README.md"
 requires-python = ">=3.8"
-license = "BSD-3-Clause"
+
+
 keywords = ["armis", "api", "development"]
 
 authors = [
@@ -62,6 +63,7 @@ dependencies = [
 ]
 [tool.hatch.envs.default.scripts]
 test = "pytest -rExXsP --cov=armis --cov-report html:.coverage_report/html {args:tests}"
+requpdate = "pur -r requirements.txt"
 
 [[tool.hatch.envs.all.matrix]]
 python = ["3.8", "3.9", "3.10", "3.11", "3.12"]
@@ -81,24 +83,24 @@ exclude = [
 [publish.index]
 disable = true
 
-[tool.coverage.run]
-source_pkgs = ["armis", "tests"]
-branch = true
-parallel = true
-omit = [
-  "src/armis/__about__.py",
-]
-
-[tool.coverage.paths]
-armis = ["src/armis", "*/armis/src/armis"]
-tests = ["tests", "*/armis/tests"]
-
-[tool.coverage.report]
-exclude_lines = [
-  "no cov",
-  "if __name__ == .__main__.:",
-  "if TYPE_CHECKING:",
-]
+#[tool.coverage.run]
+#source_pkgs = ["armis", "tests"]
+#branch = true
+#parallel = true
+#omit = [
+#  "src/armis/__about__.py",
+#]
+
+#[tool.coverage.paths]
+#armis = ["src/armis", "*/armis/src/armis"]
+#tests = ["tests", "*/armis/tests"]
+
+#[tool.coverage.report]
+#exclude_lines = [
+#  "no cov",
+#  "if __name__ == .__main__.:",
+#  "if TYPE_CHECKING:",
+#]
 
 [tool.ruff]
 exclude = [

diff --git a/pytest.ini b/pytest.ini
@@ -0,0 +1,9 @@
+[pytest]
+pythonpath = "src"
+addopts =
+     --durations=0
+     -rExXsP
+     -vv
+     --cov=armis
+     --cov-report html:.coverage_report/html
+
diff --git a/requirements.txt b/requirements.txt
@@ -1,5 +1,5 @@
 furl==2.1.3
-httpx[http2,brotli]==0.27.0
+httpx[http2, brotli]==0.27.0
 msgspec==0.18.6
 pendulum==3.0.0
-tenacity==8.2.3
+tenacity==8.3.0
diff --git a/src/armis/__about__.py b/src/armis/__about__.py
@@ -3,4 +3,4 @@
 
 __title__ = "armis"
 __description__ = "Connect and perform actions with the Armis cloud."
-__version__ = "1.0.21"
+__version__ = "1.0.22"