From da5ad14ef509b8b01def518b8a6c029899334d5d Mon Sep 17 00:00:00 2001 From: Saimon Michelson Date: Fri, 20 Jun 2025 00:18:20 -0400 Subject: [PATCH 1/6] update docs to add changelog and disclaimer --- README.rst | 17 ++ .../UserGuides/Miscellaneous/Auditing.rst | 18 ++ .../UserGuides/Miscellaneous/Changelog.rst | 112 ++++++++++ .../UserGuides/Miscellaneous/Exceptions.rst | 140 ++++++++++++ .../source/UserGuides/Miscellaneous/Index.rst | 207 +----------------- 5 files changed, 293 insertions(+), 201 deletions(-) create mode 100644 docs/source/UserGuides/Miscellaneous/Auditing.rst create mode 100644 docs/source/UserGuides/Miscellaneous/Changelog.rst create mode 100644 docs/source/UserGuides/Miscellaneous/Exceptions.rst diff --git a/README.rst b/README.rst index 958e945f..18e015cd 100644 --- a/README.rst +++ b/README.rst @@ -78,3 +78,20 @@ root directory. .. code-block:: console $ tox + + +Disclaimer +========== + +Future versions of the CTERA Python SDK may introduce breaking changes. +A breaking change is any modification insupported functionality between released versions that may require +users to update existing integrations or configurations to upgrade successfully. +While efforts are made to minimize disruption, such changes are sometimes necessary to maintain and improve the software. + +Notice of breaking changes will be detailed in the CTERA Python SDK changelog. +Users are responsible for reviewing the changelog for each new version and thoroughly +testing the software before deploying it in production. + +By using the CTERA Python SDK, users acknowledge and agree that the SDK and its +contributors are not liable for any damages, losses, or issues arising from the use or upgrade of the software, +including those resulting from breaking changes. diff --git a/docs/source/UserGuides/Miscellaneous/Auditing.rst b/docs/source/UserGuides/Miscellaneous/Auditing.rst new file mode 100644 index 00000000..b8f16801 --- /dev/null +++ b/docs/source/UserGuides/Miscellaneous/Auditing.rst @@ -0,0 +1,18 @@ +Auditing +======== + +The SDK includes a module for recording all HTTP requests and exporting them as a Postman collection. +For more information, see: +`Import data into Postman `_ +By default, auditing is disabled for performance reasons. If you need to enable Postman auditing, use the following commands: + + +.. code-block:: python + + import cterasdk.settings + cterasdk.settings.audit.enabled = True + cterasdk.settings.audit.filename = 'name-of-your-postman-collection-file' + + admin = GlobalAdmin('tenant.ctera.com') + +.. note:: The Postman collection file is stored in your default Downloads directory. diff --git a/docs/source/UserGuides/Miscellaneous/Changelog.rst b/docs/source/UserGuides/Miscellaneous/Changelog.rst new file mode 100644 index 00000000..561f5cfe --- /dev/null +++ b/docs/source/UserGuides/Miscellaneous/Changelog.rst @@ -0,0 +1,112 @@ +Changelog +========= + +2.20.10 (2025-06-07) +-------------------- + +Improvements +^^^^^^^^^^^^ + +* Revamped the exception modules in ``cterasdk.exceptions``. +* Added support for file-walk operations without specifying a path (defaults to the root directory). +* Implemented automatic file rename during upload if the destination path includes a file name that already exists. + +*Related issues and pull requests on GitHub:* `#300 `_ + +2.20.9 (2025-06-06) +------------------- + +Improvements +^^^^^^^^^^^^ + +* Introduced new exceptions for HTTP errors. +* Added support for listing and walking directories via WebDAV on the Edge Filer using ``AsyncEdge`` and ``Edge`` clients. +* Added a method to check if a file or folder exists. + +*Related issues and pull requests on GitHub:* `#299 `_ + + +2.20.8 (2025-06-04) +------------------- + +What's New +^^^^^^^^^^ + +* Added compatibility for CTERA Direct IO with CTERA Portal v8.3. + +*Related issues and pull requests on GitHub:* `#298 `_ + + +2.20.7 (2025-06-02) +------------------- + +Improvements +^^^^^^^^^^^^ + +* Updated ``cterasdk.common.object.Object`` to inherit from ``MutableMapping``, enabling dictionary-like access. +* Added support for the HTTP PROPFIND method. + +*Related issues and pull requests on GitHub:* `#297 `_ + + +2.20.6 (2025-05-30) +------------------- + +Bug Fixes +^^^^^^^^^ + +* Added support for deleting multiple files on the Edge Filer in a single call. + +*Related issues and pull requests on GitHub:* `#296 `_ + + +2.20.5 (2025-05-20) +------------------- + +Bug Fixes +^^^^^^^^^ + +* Fixed an issue where ``AsyncGlobalAdmin`` could not browse Team Portal tenants. + + +2.20.4 (2025-05-19) +------------------- + +Bug Fixes +^^^^^^^^^ + +* Moved instantiation of the TCP connector to the point of ``ClientSession`` creation. + +*Related issues and pull requests on GitHub:* `#295 `_ + + +2.20.3 (2025-05-18) +------------------- + +What's New +^^^^^^^^^^ + +* This version introduces a new ``AsyncEdge`` object for asynchronous access to the CTERA Edge Filer. +* Supported file browser operations include: + ``listdir``, ``handle``, ``handle_many``, ``download``, ``download_many``, + ``upload``, ``upload_file``, ``mkdir``, ``makedirs``, ``copy``, ``move``, and ``delete``. + +Improvements +^^^^^^^^^^^^ + +* Logging is no longer enabled by default. As of this version, it is the responsibility of the client application to configure logging explicitly. + This change aligns with best practices for libraries and allows greater flexibility in how logs are managed. + +* Introduced improved configuration settings to support both synchronous and asynchronous access to the CTERA Portal and Edge Filers. + + .. code-block:: python + + # Disable TLS verification for CTERA Portal clients + cterasdk.settings.core.syn.settings.connector.ssl = False # GlobalAdmin, ServicesPortal + cterasdk.settings.core.asyn.settings.connector.ssl = False # AsyncGlobalAdmin, AsyncServicesPortal + + # Disable TLS verification for CTERA Edge Filer clients + cterasdk.settings.edge.syn.settings.connector.ssl = False # Edge + cterasdk.settings.edge.asyn.settings.connector.ssl = False # AsyncEdge + +*Related issues and pull requests on GitHub:* `#294 `_ diff --git a/docs/source/UserGuides/Miscellaneous/Exceptions.rst b/docs/source/UserGuides/Miscellaneous/Exceptions.rst new file mode 100644 index 00000000..82882d5b --- /dev/null +++ b/docs/source/UserGuides/Miscellaneous/Exceptions.rst @@ -0,0 +1,140 @@ +Exceptions +========== + +.. autoclass:: cterasdk.exceptions.CTERAException + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.ObjectNotFoundException + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.InputError + :noindex: + :members: + :show-inheritance: + +Session +------- + +.. autoclass:: cterasdk.exceptions.session.NotLoggedIn + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.session.SessionExpired + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.session.ContextError + :noindex: + :members: + :show-inheritance: + +I/O +--- + +.. autoclass:: cterasdk.exceptions.io.RemoteStorageException + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.ResourceNotFoundError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.NotADirectory + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.ResourceExistsError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.PathValidationError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.NameSyntaxError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.ReservedNameError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.io.RestrictedPathError + :noindex: + :members: + :show-inheritance: + +Notification Service +-------------------- + +.. autoclass:: cterasdk.exceptions.notifications.NotificationsError + :noindex: + :members: + :show-inheritance: + + +HTTP Transport +-------------- + +.. autoclass:: cterasdk.exceptions.transport.HTTPError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.BadRequest + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.Unauthorized + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.Forbidden + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.NotFound + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.Unprocessable + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.InternalServerError + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.BadGateway + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.ServiceUnavailable + :noindex: + :members: + :show-inheritance: + +.. autoclass:: cterasdk.exceptions.transport.GatewayTimeout + :noindex: + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/UserGuides/Miscellaneous/Index.rst b/docs/source/UserGuides/Miscellaneous/Index.rst index daf0d709..d6217b98 100644 --- a/docs/source/UserGuides/Miscellaneous/Index.rst +++ b/docs/source/UserGuides/Miscellaneous/Index.rst @@ -2,205 +2,10 @@ Miscellaneous ============= +.. toctree:: + :caption: CTERA Edge Filer + :maxdepth: 5 -Exceptions -========== - -.. autoclass:: cterasdk.exceptions.CTERAException - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.ObjectNotFoundException - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.InputError - :noindex: - :members: - :show-inheritance: - -Session -------- - -.. autoclass:: cterasdk.exceptions.session.NotLoggedIn - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.session.SessionExpired - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.session.ContextError - :noindex: - :members: - :show-inheritance: - -I/O ---- - -.. autoclass:: cterasdk.exceptions.io.RemoteStorageException - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.ResourceNotFoundError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.NotADirectory - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.ResourceExistsError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.PathValidationError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.NameSyntaxError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.ReservedNameError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.io.RestrictedPathError - :noindex: - :members: - :show-inheritance: - -Notification Service --------------------- - -.. autoclass:: cterasdk.exceptions.notifications.NotificationsError - :noindex: - :members: - :show-inheritance: - - -HTTP Transport --------------- - -.. autoclass:: cterasdk.exceptions.transport.HTTPError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.BadRequest - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.Unauthorized - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.Forbidden - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.NotFound - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.Unprocessable - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.InternalServerError - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.BadGateway - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.ServiceUnavailable - :noindex: - :members: - :show-inheritance: - -.. autoclass:: cterasdk.exceptions.transport.GatewayTimeout - :noindex: - :members: - :show-inheritance: - -Auditing -======== - -The SDK includes a module for recording all HTTP requests and exporting them as a Postman collection. -For more information, see: -`Import data into Postman `_ -By default, auditing is disabled for performance reasons. If you need to enable Postman auditing, use the following commands: - - -.. code-block:: python - - import cterasdk.settings - cterasdk.settings.audit.enabled = True - cterasdk.settings.audit.filename = 'name-of-your-postman-collection-file' - - admin = GlobalAdmin('tenant.ctera.com') - -.. note:: The Postman collection file is stored in your default Downloads directory. - - -Serialization -============= - -This library features JSON and XML serialization, in alignment with the CTERA API schema. - -.. autofunction:: cterasdk.convert.serializers.toxmlstr - :noindex: - -.. code-block:: python - - user = Object() - user.name = 'alice' - user.firstName = 'Alice' - user.lastName = 'Wonderland' - user.email = 'alice@adventures.com' - user.password = 'Passw0rd1!' - print(toxmlstr(user)) - print(toxmlstr(user, True)) - -.. autofunction:: cterasdk.convert.serializers.tojsonstr - :noindex: - -.. code-block:: python - - user = Object() - user.name = 'alice' - user.firstName = 'Alice' - user.lastName = 'Wonderland' - user.email = 'alice@adventures.com' - user.password = 'Passw0rd1!' - print(tojsonstr(user)) - { - "lastName": "Wonderland", - "password": "Passw0rd1!", - "name": "alice", - "firstName": "Alice", - "email": "alice@adventures.com" - } - print(tojsonstr(user, False)) - {"lastName": "Wonderland", "password": "Passw0rd1!", "name": "alice", "firstName": "Alice", "email": "alice@adventures.com"} + Auditing + Exceptions + Changelog From 1831b3ce7dccfb811aecf0e3b7a0f90e3ff8e003 Mon Sep 17 00:00:00 2001 From: Saimon Michelson Date: Fri, 20 Jun 2025 00:31:12 -0400 Subject: [PATCH 2/6] pass lint --- docs/source/UserGuides/Miscellaneous/Changelog.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/source/UserGuides/Miscellaneous/Changelog.rst b/docs/source/UserGuides/Miscellaneous/Changelog.rst index 561f5cfe..91ef8c17 100644 --- a/docs/source/UserGuides/Miscellaneous/Changelog.rst +++ b/docs/source/UserGuides/Miscellaneous/Changelog.rst @@ -87,14 +87,15 @@ What's New ^^^^^^^^^^ * This version introduces a new ``AsyncEdge`` object for asynchronous access to the CTERA Edge Filer. -* Supported file browser operations include: - ``listdir``, ``handle``, ``handle_many``, ``download``, ``download_many``, +* Supported file browser operations include: + ``listdir``, ``handle``, ``handle_many``, ``download``, ``download_many``, ``upload``, ``upload_file``, ``mkdir``, ``makedirs``, ``copy``, ``move``, and ``delete``. Improvements ^^^^^^^^^^^^ -* Logging is no longer enabled by default. As of this version, it is the responsibility of the client application to configure logging explicitly. +* Logging is no longer enabled by default. As of this version, it is the responsibility of the + client application to configure logging explicitly. This change aligns with best practices for libraries and allows greater flexibility in how logs are managed. * Introduced improved configuration settings to support both synchronous and asynchronous access to the CTERA Portal and Edge Filers. @@ -110,3 +111,4 @@ Improvements cterasdk.settings.edge.asyn.settings.connector.ssl = False # AsyncEdge *Related issues and pull requests on GitHub:* `#294 `_ + From 4330af1d55f1dd0ada86c1845dff9d8b804f8859 Mon Sep 17 00:00:00 2001 From: Saimon Michelson Date: Fri, 20 Jun 2025 00:37:10 -0400 Subject: [PATCH 3/6] update changelog and exceptions --- .../UserGuides/Miscellaneous/Changelog.rst | 34 +++++++++---------- .../UserGuides/Miscellaneous/Exceptions.rst | 2 +- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/source/UserGuides/Miscellaneous/Changelog.rst b/docs/source/UserGuides/Miscellaneous/Changelog.rst index 91ef8c17..350d4a18 100644 --- a/docs/source/UserGuides/Miscellaneous/Changelog.rst +++ b/docs/source/UserGuides/Miscellaneous/Changelog.rst @@ -1,8 +1,8 @@ Changelog ========= -2.20.10 (2025-06-07) --------------------- +2.20.10 +------- Improvements ^^^^^^^^^^^^ @@ -13,8 +13,8 @@ Improvements *Related issues and pull requests on GitHub:* `#300 `_ -2.20.9 (2025-06-06) -------------------- +2.20.9 +------ Improvements ^^^^^^^^^^^^ @@ -26,8 +26,8 @@ Improvements *Related issues and pull requests on GitHub:* `#299 `_ -2.20.8 (2025-06-04) -------------------- +2.20.8 +------ What's New ^^^^^^^^^^ @@ -37,20 +37,20 @@ What's New *Related issues and pull requests on GitHub:* `#298 `_ -2.20.7 (2025-06-02) -------------------- +2.20.7 +------ Improvements ^^^^^^^^^^^^ -* Updated ``cterasdk.common.object.Object`` to inherit from ``MutableMapping``, enabling dictionary-like access. +* Updated :py:class:`cterasdk.common.object.Object` to inherit from ``MutableMapping``, enabling dictionary-like access. * Added support for the HTTP PROPFIND method. *Related issues and pull requests on GitHub:* `#297 `_ -2.20.6 (2025-05-30) -------------------- +2.20.6 +------ Bug Fixes ^^^^^^^^^ @@ -60,8 +60,8 @@ Bug Fixes *Related issues and pull requests on GitHub:* `#296 `_ -2.20.5 (2025-05-20) -------------------- +2.20.5 +------ Bug Fixes ^^^^^^^^^ @@ -69,8 +69,8 @@ Bug Fixes * Fixed an issue where ``AsyncGlobalAdmin`` could not browse Team Portal tenants. -2.20.4 (2025-05-19) -------------------- +2.20.4 +------ Bug Fixes ^^^^^^^^^ @@ -80,8 +80,8 @@ Bug Fixes *Related issues and pull requests on GitHub:* `#295 `_ -2.20.3 (2025-05-18) -------------------- +2.20.3 +------ What's New ^^^^^^^^^^ diff --git a/docs/source/UserGuides/Miscellaneous/Exceptions.rst b/docs/source/UserGuides/Miscellaneous/Exceptions.rst index 82882d5b..35a309a0 100644 --- a/docs/source/UserGuides/Miscellaneous/Exceptions.rst +++ b/docs/source/UserGuides/Miscellaneous/Exceptions.rst @@ -137,4 +137,4 @@ HTTP Transport .. autoclass:: cterasdk.exceptions.transport.GatewayTimeout :noindex: :members: - :show-inheritance: \ No newline at end of file + :show-inheritance: From e041eb4166d372d52577f2ba719401d580e2acf6 Mon Sep 17 00:00:00 2001 From: Saimon Michelson Date: Fri, 20 Jun 2025 00:38:29 -0400 Subject: [PATCH 4/6] update compatibility notice --- README.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 18e015cd..35b57c85 100644 --- a/README.rst +++ b/README.rst @@ -79,9 +79,8 @@ root directory. $ tox - -Disclaimer -========== +Compatibility Notice +==================== Future versions of the CTERA Python SDK may introduce breaking changes. A breaking change is any modification insupported functionality between released versions that may require From e1830718ed15fcd0c3e224f5286641fd31655604 Mon Sep 17 00:00:00 2001 From: Saimon Michelson Date: Fri, 20 Jun 2025 00:40:57 -0400 Subject: [PATCH 5/6] add 2.20.11 version changelog --- docs/source/UserGuides/Miscellaneous/Changelog.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/source/UserGuides/Miscellaneous/Changelog.rst b/docs/source/UserGuides/Miscellaneous/Changelog.rst index 350d4a18..22791370 100644 --- a/docs/source/UserGuides/Miscellaneous/Changelog.rst +++ b/docs/source/UserGuides/Miscellaneous/Changelog.rst @@ -1,6 +1,15 @@ Changelog ========= +2.20.11 +------- + +Improvements +^^^^^^^^^^^^ + +* Added a compatibility notice. +* Included the changelog in the CTERA Python SDK documentation. + 2.20.10 ------- From 5b2516862f2a6ba2cae74a67bb58d6599eebee96 Mon Sep 17 00:00:00 2001 From: Saimon Michelson Date: Fri, 20 Jun 2025 00:41:58 -0400 Subject: [PATCH 6/6] update PR to 301 --- docs/source/UserGuides/Miscellaneous/Changelog.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/UserGuides/Miscellaneous/Changelog.rst b/docs/source/UserGuides/Miscellaneous/Changelog.rst index 22791370..f0309bfd 100644 --- a/docs/source/UserGuides/Miscellaneous/Changelog.rst +++ b/docs/source/UserGuides/Miscellaneous/Changelog.rst @@ -10,6 +10,8 @@ Improvements * Added a compatibility notice. * Included the changelog in the CTERA Python SDK documentation. +*Related issues and pull requests on GitHub:* `#301 `_ + 2.20.10 -------