diff --git a/README.rst b/README.rst index 958e945f..35b57c85 100644 --- a/README.rst +++ b/README.rst @@ -78,3 +78,19 @@ root directory. .. code-block:: console $ tox + +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 +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..f0309bfd --- /dev/null +++ b/docs/source/UserGuides/Miscellaneous/Changelog.rst @@ -0,0 +1,125 @@ +Changelog +========= + +2.20.11 +------- + +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 +------- + +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 +------ + +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 +------ + +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 +------ + +Improvements +^^^^^^^^^^^^ + +* 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 +------ + +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 +------ + +Bug Fixes +^^^^^^^^^ + +* Fixed an issue where ``AsyncGlobalAdmin`` could not browse Team Portal tenants. + + +2.20.4 +------ + +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 +------ + +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..35a309a0 --- /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: 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