V03 issue681 3 (python API breakage.) (#687)

* for #681 API change... ugh will explain in issue itself. * updating tutorials for API change (broker -> properties) #681 * Another API change #681 add finalize() as a public entry point. * not sure why it isn't the name of the class * messageCountMax off by one. #681 * adding a little documentation in the config.py #681 * changeing conversion unknown thing from error to warning * credentials.py documenting API ane privating some entry points for clarity. #681 * more documentation of breaking change for #681 * french translation of #681 fixups to API examples, also fixed CLI_with_flowcb that was broken. reviewed and discussed in weekly meeting and agreed.
MetPX · May 29, 2023 · 0029b4e · 0029b4e
1 parent b0ae154
commit 0029b4e
Show file tree

Hide file tree

Showing 24 changed files with 929 additions and 567 deletions.
diff --git a/docs/source/How2Guides/UPGRADING.rst b/docs/source/How2Guides/UPGRADING.rst
@@ -39,6 +39,35 @@ Installation Instructions
 git
 ---
 
+3.0.40
+------
+
+*CHANGE*:  Python API breaking changes
+
+    for sarracenia.moth, now specify broker as options['broker'] instead of as
+    a separate parameter:
+
+    before:
+
+    * Moth(broker: url, options: dict, is_subsubscriber: bool) -> Config
+    * pubFactory( broker, options ) -> Config
+    * subFactory( broker, options ) -> Config
+
+    after:
+
+    * Moth( options: dict, is_subscribe: bool) -> Config
+    * pubFactory( options ) -> Config
+    * subFactory( options ) -> Config
+
+    sarracenia.config API:
+
+     now should call **sarracenia.config.finalize()**
+     after having set options  and before being used.
+     This routine reconciles the settings provided and builds
+     some derived ones.
+
+
+
 3.0.37
 ------
 

diff --git a/docs/source/Tutorials/1_CLI_introduction.ipynb b/docs/source/Tutorials/1_CLI_introduction.ipynb
diff --git a/docs/source/Tutorials/2_CLI_with_flowcb_demo.ipynb b/docs/source/Tutorials/2_CLI_with_flowcb_demo.ipynb
diff --git a/docs/source/Tutorials/3_api_flow_demo.ipynb b/docs/source/Tutorials/3_api_flow_demo.ipynb
diff --git a/docs/source/Tutorials/4_api_moth_sub_demo.ipynb b/docs/source/Tutorials/4_api_moth_sub_demo.ipynb
diff --git a/docs/source/Tutorials/5_api_moth_post_demo.ipynb b/docs/source/Tutorials/5_api_moth_post_demo.ipynb
@@ -23,16 +23,19 @@
    "execution_count": 1,
    "id": "prescribed-mortgage",
    "metadata": {
-    "scrolled": true
+    "scrolled": false
    },
    "outputs": [
     {
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2022-02-04 14:56:31,477 [DEBUG] amqp _on_start Start from server, version: 0.9, properties: {'capabilities': {'publisher_confirms': True, 'exchange_exchange_bindings': True, 'basic.nack': True, 'consumer_cancel_notify': True, 'connection.blocked': True, 'consumer_priorities': True, 'authentication_failure_close': True, 'per_consumer_qos': True, 'direct_reply_to': True}, 'cluster_name': 'rabbit@flow', 'copyright': 'Copyright (c) 2007-2019 Pivotal Software, Inc.', 'information': 'Licensed under the MPL 1.1. Website: https://rabbitmq.com', 'platform': 'Erlang/OTP 22.2.7', 'product': 'RabbitMQ', 'version': '3.8.2'}, mechanisms: [b'AMQPLAIN'], locales: ['en_US']\n",
-      "2022-02-04 14:56:31,494 [DEBUG] amqp __init__ using channel_id: 1\n",
-      "2022-02-04 14:56:31,529 [DEBUG] amqp _on_open_ok Channel open\n"
+      "2023-05-27 11:02:29,889 [DEBUG] amqp _on_start Start from server, version: 0.9, properties: {'capabilities': {'publisher_confirms': True, 'exchange_exchange_bindings': True, 'basic.nack': True, 'consumer_cancel_notify': True, 'connection.blocked': True, 'consumer_priorities': True, 'authentication_failure_close': True, 'per_consumer_qos': True, 'direct_reply_to': True}, 'cluster_name': 'rabbit@fractal', 'copyright': 'Copyright (c) 2007-2022 VMware, Inc. or its affiliates.', 'information': 'Licensed under the MPL 2.0. Website: https://rabbitmq.com', 'platform': 'Erlang/OTP 24.2.1', 'product': 'RabbitMQ', 'version': '3.9.13'}, mechanisms: [b'PLAIN', b'AMQPLAIN'], locales: ['en_US']\n",
+      "2023-05-27 11:02:29,890 [DEBUG] amqp __init__ using channel_id: 1\n",
+      "2023-05-27 11:02:29,890 [DEBUG] amqp _on_open_ok Channel open\n",
+      "2023-05-27 11:02:29,891 [DEBUG] sarracenia.moth.amqp __putSetup putSetup ... 1. declaring xpublic\n",
+      "2023-05-27 11:02:29,892 [INFO] sarracenia.moth.amqp __putSetup exchange declared: xpublic (as: amqp://tfeed@localhost)\n",
+      "2023-05-27 11:02:29,892 [DEBUG] sarracenia.moth.amqp __putSetup putSetup ... Done!\n"
      ]
     }
    ],
@@ -54,7 +57,7 @@
     "cfg.post_baseDir = '/tmp'\n",
     "\n",
     "# moth wants a dict as options, rather than sarracenia.config.Config instance.\n",
-    "posting_engine = sarracenia.moth.Moth.pubFactory(cfg.broker, cfg.dictify() )"
+    "posting_engine = sarracenia.moth.Moth.pubFactory( cfg.dictify() )"
    ]
   },
   {
@@ -104,14 +107,16 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2022-02-04 14:56:38,509 [DEBUG] amqp collect Closed channel #1\n"
+      "2023-05-27 11:02:41,866 [DEBUG] sarracenia __computeIntegrity xattr sum too old\n",
+      "2023-05-27 11:02:41,868 [DEBUG] sarracenia.moth.amqp putNewMessage published body: {\"pubTime\": \"20230527T150241.865911961\", \"relPath\": \"sample.txt\", \"baseUrl\": \"http://host\", \"mode\": \"664\", \"size\": 335, \"mtime\": \"20230527T150237.927556038\", \"atime\": \"20230525T031938.0635721684\", \"integrity\": {\"method\": \"sha512\", \"value\": \"w5ZwUT1IMAjnQT6TLR9NSLzG5RKijhxq46FjMx5UWtsHM/FNOaYNRmGwonIPfnhE5xUORf3z5dRyI6zdL6ygNw==\"}} headers: {} to xpublic under: v03 \n",
+      "2023-05-27 11:02:41,868 [DEBUG] amqp collect Closed channel #1\n"
      ]
     },
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "{'exchange': 'xpublic', 'local_offset': 0, '_deleteOnPost': {'exchange', 'local_offset', 'new_relPath', 'new_subtopic', 'new_file', 'new_baseUrl', 'new_dir'}, 'pubTime': '20220204T205638.499809504', 'new_dir': '/tmp', 'new_file': 'sample.txt', 'new_baseUrl': 'http://host', 'new_relPath': 'sample.txt', 'new_subtopic': [], 'relPath': 'sample.txt', 'subtopic': [], 'baseUrl': 'http://host', 'from_cluster': 'localhost', 'size': 335, 'mtime': '20220204T205635.203999996', 'atime': '20220204T195639.0199999809', 'mode': '664', 'integrity': {'method': 'sha512', 'value': 'w5ZwUT1IMAjnQT6TLR9NSLzG5RKijhxq46FjMx5UWtsHM/FNOaYNRmGwonIPfnhE5xUORf3z5dRyI6zdL6ygNw=='}}\n"
+      "{'_format': 'v03', '_deleteOnPost': {'local_offset', 'new_baseUrl', 'new_dir', 'new_subtopic', 'new_file', 'subtopic', '_format', 'exchange', 'new_relPath', 'post_format'}, 'exchange': 'xpublic', 'local_offset': 0, 'pubTime': '20230527T150241.865911961', 'new_dir': '/tmp', 'new_file': 'sample.txt', 'post_format': 'v03', 'new_baseUrl': 'http://host', 'new_relPath': 'sample.txt', 'new_subtopic': [], 'relPath': 'sample.txt', 'subtopic': [], 'baseUrl': 'http://host', 'mode': '664', 'size': 335, 'mtime': '20230527T150237.927556038', 'atime': '20230525T031938.0635721684', 'integrity': {'method': 'sha512', 'value': 'w5ZwUT1IMAjnQT6TLR9NSLzG5RKijhxq46FjMx5UWtsHM/FNOaYNRmGwonIPfnhE5xUORf3z5dRyI6zdL6ygNw=='}}\n"
      ]
     }
    ],
@@ -139,7 +144,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -153,7 +158,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.10.6"
   }
  },
  "nbformat": 4,

diff --git a/docs/source/fr/CommentFaire/MiseANiveau.rst b/docs/source/fr/CommentFaire/MiseANiveau.rst
@@ -38,6 +38,30 @@ Instructions d’installation
 git
 ---
 
+*CHANGEMENT*:  l'interface de programmation (API) python a subit un changement de rupture
+
+    pour la classe sarracenia.moth, il faut maintenant specifier l'options['broker'] au lieu
+    de le fournir commen argument séparé.
+
+    avant:
+
+    * Moth(broker: url, options: dict, is_subsubscriber: bool) -> Config
+    * pubFactory( broker, options ) -> Config
+    * subFactory( broker, options ) -> Config
+
+    après:
+
+    * Moth( options: dict, is_subscribe: bool) -> Config
+    * pubFactory( options ) -> Config
+    * subFactory( options ) -> Config
+
+    sarracenia.config API:
+
+     Il est recommandé d´appeller **sarracenia.config.finalize()**
+     après avoir fourni les options.  Celui-ci interpole et complète
+     les valeurs d´options pou qu´ils soient utilisable par les
+     composantes.  
+
 3.0.26
 ------