Merge pull request #59 from NikitaZotov/refactor/api_names

refactor: clarify all sc-client names

docs/changelog.md

@@ -4,6 +4,62 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Breaking changes
+ - This version is compatible with version of the sc-machine 0.10.0. All API methods were redesigned. Incorrect ones were removed, new ones were added. See table below, to learn more about changes.
+
+  | Deprecated method                       | Substitution method                        | 
+  |-----------------------------------------|--------------------------------------------|
+  | check_elements                          | get_elements_types                          |
+  | create_elements                         | generate_elements                          |
+  | create_node                             | generate_node                              |
+  | create_link                             | generate_link                              |
+  | create_edge                             | generate_connector                         |
+  | create_elements_by_scs                  | generate_elements_by_scs                   | 
+  | delete_elements                         | erase_elements                             |
+  | get_links_by_contents                   | search_links_by_contentss                   |
+  | get_links_by_content_substring          | search_links_by_contents_substrings         |
+  | get_links_contents_by_content_substring | search_link_contents_by_content_substrings |
+  | template_search                         | search_by_template                         |
+  | template_generate                       | generate_by_template                       |
+  | triple_with_relation                    | quintuple                                  |
+  | events_create                           | create_elementary_event_subscriptions      |
+  | events_destroy                          | destroy_elementary_event_subscriptions     |
+  | is_event_valid                          | is_event_subscriptions_valid               |
+
+ - `ScEvent` class was renamed to `ScEventSubscription`, `ScEventParams` class was renamed to `ScEventSubscriptionParams`, and sc-event types in `ScEventType` were changed according to the table below.
+
+  | Removed sc-event type  | Substitution sc-event type  |
+  |------------------------|-----------------------------|
+  | ADD_OUTGOING_EDGE      | AFTER_GENERATE_OUTGOING_ARC |
+  | ADD_INGOING_EDGE       | AFTER_GENERATE_INCOMING_ARC  |
+  | REMOVE_OUTGOING_EDGE   | BEFORE_ERASE_OUTGOING_ARC   |
+  | REMOVE_INGOING_EDGE    | BEFORE_ERASE_INCOMING_ARC    |
+  | REMOVE_ELEMENT         | BEFORE_ERASE_ELEMENT        |
+  | CONTENT_CHANGE         | BEFORE_CHANGE_LINK_CONTENT  |
+
+  New sc-event types: `AFTER_GENERATE_CONNECTOR`, `AFTER_GENERATE_EDGE`, `BEFORE_ERASE_CONNECTOR`, `BEFORE_ERASE_EDGE` were added.
+
+### Added
+ - sc-event types: `AFTER_GENERATE_CONNECTOR`, `AFTER_GENERATE_OUTGOING_ARC`, `AFTER_GENERATE_INCOMING_ARC`, `AFTER_GENERATE_EDGE`, `BEFORE_ERASE_CONNECTOR`, `BEFORE_ERASE_OUTGOING_ARC`, `BEFORE_ERASE_INCOMING_ARC`,  `BEFORE_ERASE_EDGE`, `BEFORE_ERASE_ELEMENT`, `BEFORE_CHANGE_LINK_CONTENT`
+ - ScClient methods: `get_elements_types`, `generate_elements`, `generate_node`, `generate_link`, `generate_connector`, `generate_elements_by_scs`, `erase_elements`, `search_links_by_contentss`, `search_links_by_contents_substrings`, `search_link_contents_by_content_substrings`, `search_by_template`, `generate_by_template`, `create_elementary_event_subscriptions`, `destroy_elementary_event_subscriptions`, `is_event_subscriptions_valid`
+ - ScTemplate methods: `quintuple`
+
+### Changed
+ - `ScEvent` class was renamed to `ScEventSubscription`
+ - `ScEventParams` class was renamed to `ScEventSubscriptionParams`
+
+### Deprecated
+ - ScClient methods: `check_elements`, `create_elements`, `create_node`, `create_link`, `create_edge`, `create_elements_by_scs`, `delete_elements`, `get_links_by_contents`, `get_links_by_content_substring`, `get_links_contents_by_content_substring`, `template_search`, `template_generate`, `events_create`, `events_destroy`, `is_event_valid`
+ - ScTemplate methods: `triple_with_relation`
+
+### Removed
+ - sc-event types: `ADD_OUTGOING_EDGE`, `ADD_INGOING_EDGE`, `REMOVE_OUTGOING_EDGE`, `REMOVE_INGOING_EDGE`, `REMOVE_ELEMENT`, `CONTENT_CHANGE`
+ - Deprecated ScTemplateResult `size` method
+ - Deprecated ScTemplateItem as list
+ - Deprecated ScTemplateResult `for_each_triple` method
+ - Deprecated `ScAgent` and `ScModule` classes
+
 ## [0.3.1]
 ### Fixed
 - Undefined python interpreter version in CI

src/sc_client/client/__init__.py

@@ -7,19 +7,31 @@
 from sc_client.client._api import (
     check_elements,
     connect,
+    create_elementary_event_subscriptions,
     create_elements,
     create_elements_by_scs,
     delete_elements,
+    destroy_elementary_event_subscriptions,
     disconnect,
+    erase_elements,
     events_create,
     events_destroy,
+    generate_by_template,
+    generate_elements,
+    generate_elements_by_scs,
+    get_elements_types,
     get_link_content,
     get_links_by_content,
     get_links_by_content_substring,
     get_links_contents_by_content_substring,
     is_connected,
+    is_event_subscription_valid,
     is_event_valid,
     resolve_keynodes,
+    search_by_template,
+    search_link_contents_by_content_substrings,
+    search_links_by_contents,
+    search_links_by_contents_substrings,
     set_error_handler,
     set_link_contents,
     set_reconnect_handler,

src/sc_client/client/_api.py

@@ -6,15 +6,17 @@
 
 from __future__ import annotations
 
+import warnings
+
 from sc_client import session
 from sc_client.constants import common, exceptions
 from sc_client.constants.numeric import SERVER_RECONNECT_RETRIES, SERVER_RECONNECT_RETRY_DELAY
 from sc_client.constants.sc_types import ScType
 from sc_client.models import (
     ScAddr,
     ScConstruction,
-    ScEvent,
-    ScEventParams,
+    ScEventSubscription,
+    ScEventSubscriptionParams,
     ScIdtfResolveParams,
     ScLinkContent,
     SCsText,
@@ -51,20 +53,49 @@ def set_reconnect_handler(**reconnect_kwargs) -> None:
     )
 
 
+def get_elements_types(*addrs: ScAddr) -> list[ScType]:
+    return session.execute(common.ClientCommand.GET_ELEMENTS_TYPES, *addrs)
+
+
 def check_elements(*addrs: ScAddr) -> list[ScType]:
-    return session.execute(common.ClientCommand.CHECK_ELEMENTS, *addrs)
+    warnings.warn(
+        "ScClient 'check_elements' method is deprecated. Use `get_elements_types` method instead.", DeprecationWarning
+    )
+    return get_elements_types(*addrs)
+
+
+def generate_elements(constr: ScConstruction) -> list[ScAddr]:
+    return session.execute(common.ClientCommand.GENERATE_ELEMENTS, constr)
 
 
 def create_elements(constr: ScConstruction) -> list[ScAddr]:
-    return session.execute(common.ClientCommand.CREATE_ELEMENTS, constr)
+    warnings.warn(
+        "ScClient 'create_elements' method is deprecated. Use `generate_elements` method instead.", DeprecationWarning
+    )
+    return generate_elements(constr)
+
+
+def generate_elements_by_scs(text: SCsText) -> list[bool]:
+    return session.execute(common.ClientCommand.GENERATE_ELEMENTS_BY_SCS, text)
 
 
 def create_elements_by_scs(text: SCsText) -> list[bool]:
-    return session.execute(common.ClientCommand.CREATE_ELEMENTS_BY_SCS, text)
+    warnings.warn(
+        "ScClient 'create_elements_by_scs' method is deprecated. Use `generate_elements_by_scs` method instead.",
+        DeprecationWarning,
+    )
+    return generate_elements_by_scs(text)
+
+
+def erase_elements(*addrs: ScAddr) -> bool:
+    return session.execute(common.ClientCommand.ERASE_ELEMENTS, *addrs)
 
 
 def delete_elements(*addrs: ScAddr) -> bool:
-    return session.execute(common.ClientCommand.DELETE_ELEMENTS, *addrs)
+    warnings.warn(
+        "ScClient 'delete_elements' method is deprecated. Use `erase_elements` method instead.", DeprecationWarning
+    )
+    return erase_elements(*addrs)
 
 
 def set_link_contents(*contents: ScLinkContent) -> bool:
@@ -75,43 +106,110 @@ def get_link_content(*addr: ScAddr) -> list[ScLinkContent]:
     return session.execute(common.ClientCommand.GET_LINK_CONTENT, *addr)
 
 
+def search_links_by_contents(*contents: ScLinkContent | ScLinkContentData) -> list[list[ScAddr]]:
+    return session.execute(common.ClientCommand.SEARCH_LINKS_BY_CONTENT, *contents)
+
+
 def get_links_by_content(*contents: ScLinkContent | ScLinkContentData) -> list[list[ScAddr]]:
-    return session.execute(common.ClientCommand.GET_LINKS_BY_CONTENT, *contents)
+    warnings.warn(
+        "ScClient 'get_links_by_content' method is deprecated. Use `search_links_by_contents` method instead.",
+        DeprecationWarning,
+    )
+    return search_links_by_contents(*contents)
+
+
+def search_links_by_contents_substrings(*contents: ScLinkContent | ScLinkContentData) -> list[list[ScAddr]]:
+    return session.execute(common.ClientCommand.SEARCH_LINKS_BY_CONTENT_SUBSTRING, *contents)
 
 
 def get_links_by_content_substring(*contents: ScLinkContent | ScLinkContentData) -> list[list[ScAddr]]:
-    return session.execute(common.ClientCommand.GET_LINKS_BY_CONTENT_SUBSTRING, *contents)
+    warnings.warn(
+        "ScClient 'get_links_by_content_substring' method is deprecated. Use `search_links_by_contents_substrings` method instead.",
+        DeprecationWarning,
+    )
+    return search_links_by_contents_substrings(*contents)
+
+
+def search_link_contents_by_content_substrings(*contents: ScLinkContent | ScLinkContentData) -> list[list[ScAddr]]:
+    return session.execute(common.ClientCommand.SEARCH_LINKS_CONTENTS_BY_CONTENT_SUBSTRING, *contents)
 
 
 def get_links_contents_by_content_substring(*contents: ScLinkContent | ScLinkContentData) -> list[list[ScAddr]]:
-    return session.execute(common.ClientCommand.GET_LINKS_CONTENTS_BY_CONTENT_SUBSTRING, *contents)
+    warnings.warn(
+        "ScClient 'get_links_contents_by_content_substring' method is deprecated. Use `search_link_contents_by_content_substrings` method instead.",
+        DeprecationWarning,
+    )
+    return search_link_contents_by_content_substrings(*contents)
 
 
 def resolve_keynodes(*params: ScIdtfResolveParams) -> list[ScAddr]:
-    return session.execute(common.ClientCommand.KEYNODES, *params)
+    return session.execute(common.ClientCommand.SEARCH_KEYNODES, *params)
+
+
+def search_by_template(
+    template: ScTemplate | str | ScTemplateIdtf | ScAddr, params: ScTemplateParams = None
+) -> list[ScTemplateResult]:
+    return session.execute(common.ClientCommand.SEARCH_BY_TEMPLATE, template, params)
 
 
 def template_search(
     template: ScTemplate | str | ScTemplateIdtf | ScAddr, params: ScTemplateParams = None
 ) -> list[ScTemplateResult]:
-    return session.execute(common.ClientCommand.SEARCH_TEMPLATE, template, params)
+    warnings.warn(
+        "ScClient 'template_search' method is deprecated. Use `search_by_template` method instead.", DeprecationWarning
+    )
+    return search_by_template(template, params)
+
+
+def generate_by_template(
+    template: ScTemplate | str | ScTemplateIdtf | ScAddr, params: ScTemplateParams = None
+) -> ScTemplateResult:
+    return session.execute(common.ClientCommand.GENERATE_BY_TEMPLATE, template, params)
 
 
 def template_generate(
     template: ScTemplate | str | ScTemplateIdtf | ScAddr, params: ScTemplateParams = None
 ) -> ScTemplateResult:
-    return session.execute(common.ClientCommand.GENERATE_TEMPLATE, template, params)
+    warnings.warn(
+        "ScClient 'template_generate' method is deprecated. Use `generate_by_template` method instead.",
+        DeprecationWarning,
+    )
+    return generate_by_template(template, params)
+
+
+def create_elementary_event_subscriptions(*params: ScEventSubscriptionParams) -> list[ScEventSubscription]:
+    return session.execute(common.ClientCommand.CREATE_EVENT_SUBSCRIPTIONS, *params)
+
+
+def events_create(*params: ScEventSubscriptionParams) -> list[ScEventSubscription]:
+    warnings.warn(
+        "ScClient 'evens_create' method is deprecated. Use `create_elementary_event_subscriptions` method instead.",
+        DeprecationWarning,
+    )
+    return create_elementary_event_subscriptions(*params)
+
 
+def destroy_elementary_event_subscriptions(*event_subscriptions: ScEventSubscription) -> bool:
+    return session.execute(common.ClientCommand.DESTROY_EVENT_SUBSCRIPTIONS, *event_subscriptions)
 
-def events_create(*events: ScEventParams) -> list[ScEvent]:
-    return session.execute(common.ClientCommand.EVENTS_CREATE, *events)
 
+def events_destroy(*event_subscriptions: ScEventSubscription) -> bool:
+    warnings.warn(
+        "ScClient 'events_destroy' method is deprecated. Use `destroy_elementary_event_subscriptions` method instead.",
+        DeprecationWarning,
+    )
+    return destroy_elementary_event_subscriptions(*event_subscriptions)
 
-def events_destroy(*events: ScEvent) -> bool:
-    return session.execute(common.ClientCommand.EVENTS_DESTROY, *events)
 
+def is_event_subscription_valid(event_subscription: ScEventSubscription) -> bool:
+    if not isinstance(event_subscription, ScEventSubscription):
+        raise exceptions.InvalidTypeError("expected object types: ScEventSubscription")
+    return bool(session.get_event_subscription(event_subscription.id))
 
-def is_event_valid(event: ScEvent) -> bool:
-    if not isinstance(event, ScEvent):
-        raise exceptions.InvalidTypeError("expected object types: ScEvent")
-    return bool(session.get_event(event.id))
+
+def is_event_valid(event_subscription: ScEventSubscription) -> bool:
+    warnings.warn(
+        "ScClient 'is_event_valid' method is deprecated. Use `is_event_subscription_valid` method instead.",
+        DeprecationWarning,
+    )
+    return is_event_subscription_valid(event_subscription)

src/sc_client/client/_executor.py

@@ -7,20 +7,20 @@
 
 class Executor:
     _executor_mapper = {
-        ClientCommand.CREATE_ELEMENTS: RequestType.CREATE_ELEMENTS,
-        ClientCommand.CREATE_ELEMENTS_BY_SCS: RequestType.CREATE_ELEMENTS_BY_SCS,
-        ClientCommand.CHECK_ELEMENTS: RequestType.CHECK_ELEMENTS,
-        ClientCommand.DELETE_ELEMENTS: RequestType.DELETE_ELEMENTS,
-        ClientCommand.KEYNODES: RequestType.KEYNODES,
-        ClientCommand.GET_LINK_CONTENT: RequestType.CONTENT,
-        ClientCommand.GET_LINKS_BY_CONTENT: RequestType.CONTENT,
-        ClientCommand.GET_LINKS_BY_CONTENT_SUBSTRING: RequestType.CONTENT,
-        ClientCommand.GET_LINKS_CONTENTS_BY_CONTENT_SUBSTRING: RequestType.CONTENT,
-        ClientCommand.SET_LINK_CONTENTS: RequestType.CONTENT,
-        ClientCommand.EVENTS_CREATE: RequestType.EVENTS,
-        ClientCommand.EVENTS_DESTROY: RequestType.EVENTS,
-        ClientCommand.GENERATE_TEMPLATE: RequestType.GENERATE_TEMPLATE,
-        ClientCommand.SEARCH_TEMPLATE: RequestType.SEARCH_TEMPLATE,
+        ClientCommand.GENERATE_ELEMENTS: RequestType.GENERATE_ELEMENTS,
+        ClientCommand.GENERATE_ELEMENTS_BY_SCS: RequestType.GENERATE_ELEMENTS_BY_SCS,
+        ClientCommand.GET_ELEMENTS_TYPES: RequestType.GET_ELEMENTS_TYPES,
+        ClientCommand.ERASE_ELEMENTS: RequestType.ERASE_ELEMENTS,
+        ClientCommand.SEARCH_KEYNODES: RequestType.SEARCH_KEYNODES,
+        ClientCommand.GET_LINK_CONTENT: RequestType.HANDLE_CONTENT,
+        ClientCommand.SEARCH_LINKS_BY_CONTENT: RequestType.HANDLE_CONTENT,
+        ClientCommand.SEARCH_LINKS_BY_CONTENT_SUBSTRING: RequestType.HANDLE_CONTENT,
+        ClientCommand.SEARCH_LINKS_CONTENTS_BY_CONTENT_SUBSTRING: RequestType.HANDLE_CONTENT,
+        ClientCommand.SET_LINK_CONTENTS: RequestType.HANDLE_CONTENT,
+        ClientCommand.CREATE_EVENT_SUBSCRIPTIONS: RequestType.HANDLE_EVENT_SUBSCRIPTIONS,
+        ClientCommand.DESTROY_EVENT_SUBSCRIPTIONS: RequestType.HANDLE_EVENT_SUBSCRIPTIONS,
+        ClientCommand.GENERATE_BY_TEMPLATE: RequestType.GENERATE_BY_TEMPLATE,
+        ClientCommand.SEARCH_BY_TEMPLATE: RequestType.SEARCH_BY_TEMPLATE,
     }
 
     def __init__(self):