Copier Template: Additional development documentation on nomenclature.

documentation/ideas/nomenclature/verb-hypercategories.rst

@@ -0,0 +1,136 @@
+Categorization by Functional Area
+-------------------------------------------------------------------------------
+
+Analysis & Reporting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``assess_<data>``
+- ``calculate_<value>``
+- ``filter_<objects>``
+- ``report_<data>``
+- ``survey_<resource>``
+
+Object Lifecycle
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``modify_<object>``
+- ``produce_<object>``
+
+Resource Lifecycle
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``create_<resource>``
+- ``delete_<resource>``
+- ``ensure_<resource>``
+- ``update_<resource>``
+
+Object Access & Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``access_<object>``
+- ``restore_<object>``
+- ``save_<object>``
+
+Resource Access & Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``acquire_<resource>``
+- ``allocate_<space>``
+- ``deallocate_<space>``
+- ``query_<resource>``
+- ``release_<resource>``
+- ``reserve_<resource>``
+- ``retrieve_<resource>``
+
+Execution Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``activate_<execution-or-service>``
+- ``cancel_<future-or-reservation>``
+- ``deactivate_<execution-or-service>``
+- ``request_<action>``
+- ``schedule_<execution>``
+
+Event Handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``register_<reactor>``
+- ``deregister_<reactor>``
+- ``intercept_<exceptions>``
+
+State & Feature Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``disable_<feature>``
+- ``enable_<feature>``
+
+Verification & Validation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``assert_<resource>``
+- ``is_<member-or-state>``
+- ``probe_<resource>``
+- ``test_<assertion>``
+- ``validate_<object>``
+- ``verify_<condition>``
+
+Data Processing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``parse_<format>``
+- ``transform_<data>``
+
+Discovery & Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``configure_<component>``
+- ``discover_<value>``
+- ``examine_<resource>``
+- ``prepare_<component>``
+
+
+Categorization by Possession/Proximity
+-------------------------------------------------------------------------------
+
+In-Process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``access_<object>``
+- ``assess_<data>``
+- ``calculate_<value>``
+- ``filter_<objects>``
+- ``is_<member-or-state>``
+- ``modify_<object>``
+- ``produce_<object>``
+- ``transform_<data>``
+- ``validate_<object>``
+- ``verify_<condition>``
+
+Process External
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``acquire_<resource>``
+- ``allocate_<space>``
+- ``create_<resource>``
+- ``deallocate_<space>``
+- ``delete_<resource>``
+- ``examine_<resource>``
+- ``probe_<resource>``
+- ``query_<resource>``
+- ``release_<resource>``
+- ``reserve_<resource>``
+- ``restore_<object>``
+- ``retrieve_<resource>``
+- ``save_<object>``
+- ``survey_<resource>``
+- ``update_<resource>``
+
+Location Independent
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``activate_<execution-or-service>``
+- ``assert_<resource>``
+- ``cancel_<future-or-reservation>``
+- ``configure_<component>``
+- ``deactivate_<execution-or-service>``
+- ``deregister_<reactor>``
+- ``disable_<feature>``
+- ``discover_<value>``
+- ``display_<data>``
+- ``enable_<feature>``
+- ``ensure_<resource>``
+- ``intercept_<exceptions>``
+- ``parse_<format>``
+- ``prepare_<component>``
+- ``register_<reactor>``
+- ``render_<template>``
+- ``report_<data>``
+- ``request_<action>``
+- ``schedule_<execution>``
+- ``test_<assertion>``

template/documentation/sphinx/development/nomenclature.rst

@@ -387,6 +387,43 @@ Verb Prefixes
   ``validate_<object>``, which returns object or raises exception,
   ``is_<member-or-state>`` for type/state testing.
 
+Function Suffixes
+-------------------------------------------------------------------------------
+
+The project uses a limited set of function suffixes to indicate specific
+execution patterns:
+
+- ``_async``: Indicates asynchronous execution
+- ``_continuous``: Indicates generator/iterator return type (alternative:
+  ``_streaming`` when using Germanic-derived terms)
+- ``_recursive``: Indicates recursive execution when this is part of the
+  function's contract rather than an implementation detail
+
+Other execution patterns (parallel processing, batch operations, etc.) are
+better expressed through specific function names or appropriate use of
+threading/multiprocessing facilities.
+
+When Not to Use Suffixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Avoid suffixes for:
+
+- Implementation details (``_cached``, ``_optimized``)
+- Alternative implementations (``_safe``, ``_fallback``)
+- Batch operations (use prefix ``mass_`` or ``multi_`` prefixes instead)
+- In-place operations (use Python's established patterns like list methods)
+- Development status (``_experimental``)
+- Debugging aids (``_verbose``)
+- Parallel processing (use appropriate concurrency primitives instead)
+
+These aspects are better handled through:
+
+- Separate, clearly named functions
+- Documentation of performance characteristics
+- Version control and release management
+- Logging and debugging facilities
+- Threading and multiprocessing facilities
+
 
 Linguistic Consistency
 ===============================================================================
@@ -408,9 +445,9 @@ linguistic consistency within:
 
 Within individual names, maintain agreement between verbs and nouns:
 
-- ``shape_set`` (Germanic verb with Germanic-derived noun)
-- ``validate_sequence`` (Latin verb with Latin-derived noun)
-- ``analyze_algorithm`` (Greek verb with Greek-influenced noun)
+- ``shape_set`` (Germanic-derived verb with Germanic-derived noun)
+- ``validate_sequence`` (Latin-derived verb with Latin-derived noun)
+- ``analyze_algorithm`` (Greek-derived verb with Greek-influenced noun)
 
 Technical abbreviations (``str``, ``obj``), acronyms (``xml``, ``json``), and
 some portmanteau words are linguistically neutral and can be used with terms