Nomenclature

This guide presents naming conventions and patterns for Python and Rust projects. The lists are not exhaustive, and new patterns may emerge for specific domains or requirements.

When working with third-party APIs or established codebases, it may be appropriate to follow their existing naming conventions rather than those presented here. The goal is consistency within a given context rather than rigid adherence to these patterns.

Classes

General Guidance

• Use Async suffix for asynchronous interfaces.

• Avoid Type suffix except when fitting to existing framework. I.e., do not follow the pattern in Python’s types module unless there is good reason to do so.

Abstract Classes

• Prefix with Abstract for abstract base classes.

• Use adjective names for interface-like classes when they describe capabilities.

class AbstractDictionary:
    ''' Abstract base for dictionary types. '''

class Comparable:
    ''' Interface for objects supporting comparison. '''

class Immutable:
    ''' Interface for objects preventing modification. '''

Base Classes

• Use Base or Common suffix for base classes.

• Use Extension/Supplement (Latin-derived) or Mixin (Germanic-like) suffix for mix-in classes.

class DictionaryBase:
    ''' Base class for dictionary implementations. '''

class LoggingMixin:
    ''' Adds logging capabilities to classes. '''

Container Classes

Name based on behavior rather than implementation.

class ProducerDictionary:
    ''' Dictionary producing values on demand. '''

class QueueAsync:
    ''' Queue with asynchronous interface. '''

Decorator Classes

• Use adjectives when describing the modification.

• Use nouns when describing the resulting form.

class Comparable:
    ''' Decorator class providing comparison capabilities. '''

class Dataclass:
    ''' Decorator class creating data class. '''

Enum Classes

• Use plural nouns for enum class names.

• Use PascalCase for enum members to reflect singleton semantics.

class States:
    Initial = auto( )
    Execution = auto( )
    Complete = auto( )

Exception Classes

• Follow standard hierarchy: Omniexception -> Omnierror -> specific exceptions.

• Use present tense verbs with these patterns:

  • [<Noun>]<Verb>Failure for operation failures

  • [<Noun>]<Verb>Interruption for interrupted operations

  • [<Noun>]<Verb>Invalidity for invalid states/data

• Use [<Noun>]<Property>Error for other error cases.

class ConfigureFailure( Omnierror ):
    ''' Raised when configuration fails. '''

class AttributeInvalidity( Omnierror ):
    ''' Raised when attribute value is invalid. '''

class ProcessInterruption( Omniexception ):
    ''' Raised when process is interrupted. '''

Metaclasses

• Use Class/Factory (Latin-derived) or Builder/Maker (Germanic-derived) suffix.

class ValidatorClass( type ):
    ''' Metaclass for creating validator classes. '''

class SetBuilder( type ):
    ''' Metaclass for building set classes. '''

Special Purpose Classes

Use appropriate suffix pairs based on purpose:

• Proxy (Latin-derived) or Wrapper (Germanic-derived) for delegation patterns

• Coordinator/Manager/Supervisor (Latin-derived) or Overseer (Germanic-derived) for resource management

• Spectator/View for limited access patterns

class WeakrefWrapper:
    ''' Wraps object with weak reference semantics. '''

class ConnectionManager:
    ''' Manages database connections. '''

class DictionaryView:
    ''' Provides read-only view of dictionary. '''

Functions

General Patterns

<verb>_<noun>: Where verb describes the action and noun describes the target.

<preposition>_<noun>: For methods only. Chainable operations typically returning modified copies.

Noun Placeholders

• <attribute>: Named property or field of an object

• <component>: Distinct part of a larger system or application

• <condition>: Boolean predicate or state

• <data>: Raw or structured information, regardless of location

• <execution>: Execution context (process, thread, task) managed by current process

• <feature>: Optional functionality that can be enabled/disabled

• <format>: Data serialization format (JSON, XML, etc.)

• <future>: Planned future execution

• <object>: In-process entity (instance of a Python class)

• <reactor>: Callback or event handler

• <reservation>: Claim on future resource usage

• <resource>: Entity external to the current process (file, network service, etc.)

• <service>: Long-running process or daemon external to current process

• <space>: Memory or storage allocation

• <type>: Python type or class

Preposition Prefixes

• as_<format-or-type>: Returns copy of object in different format or type. Chainable with other methods.

• from_<format-or-type>: Class method that constructs object from specific format or type.

• with_<attribute>: Returns copy of object with modified attributes. Chainable with other methods.

Verb Prefixes

• access_<object>: Returns value via computed or indirect access (e.g., property getter, descriptor protocol). For in-process objects only.

• acquire_<resource>: Obtains exclusive access to shared resource requiring explicit release (e.g., mutex, database connection). Antonym: release_<resource>.

• activate_<execution-or-service>: Starts execution context or service. For both in-process executions and external services. Antonym: deactivate_<execution-or-service>.

• allocate_<space>: Reserves system memory or storage space for future use. Antonym: deallocate_<space>.

• assess_<data>: Examines data to derive insights or patterns.

• assert_<resource> [Python]: Verifies resource exists or condition holds, raising exception if not. [Rust]: Panics if condition fails. Related: verify_<condition> which returns boolean.

• calculate_<value>: Computes value from one or more inputs using defined algorithm.

• cancel_<future-or-reservation>: Revokes planned execution or resource claim. Antonym for both schedule_<execution> and reserve_<resource>. See these related patterns for specific usage.

• configure_<component>: Applies settings or parameters to component, preparing it for operation. Related: prepare_<component> for full initialization.

• create_<resource>: Creates new resource external to current process (e.g., file, database table). For in-process object creation, see produce_<object>. Antonym: delete_<resource>.

• deactivate_<execution-or-service>: Stops execution context or service. Antonym: activate_<execution-or-service>.

• deallocate_<space>: Frees previously allocated system memory or storage space. Antonym: allocate_<space>.

• delete_<resource>: Removes resource external to current process. [Python]: For in-process objects, we generally rely on garbage collection or context managers and do not need explicit destructors. Antonym: create_<resource>.

• deregister_<reactor>: Removes previously registered event handler or callback. Antonym: register_<reactor>.

• disable_<feature>: Deactivates optional feature or functionality. Antonym: enable_<feature>.

• discover_<value>: Detects or determines value from environment or context.

• display_<data>: Presents data in user-facing format. Synonym: present_<data>.

• enable_<feature>: Activates optional feature or functionality. Antonym: disable_<feature>.

• ensure_<resource>: Creates resource if it doesn’t exist, returns existing resource if it does. Related: create_<resource> for forced creation.

• examine_<resource>: Retrieves metadata about resource without accessing full content (e.g., file stats, HTTP HEAD).

• filter_<objects>: Returns subset of objects matching specified criteria.

• intercept_<exceptions> [Python]: Invokes functions while capturing their exceptions for later handling. Used primarily in concurrent execution contexts where multiple exceptions need collection.

• is_<member-or-state>: Tests type membership or current state. Returns boolean. Related: verify_<condition> for condition verification.

• modify_<object>: Updates in-process object state. Alternative to update_<resource> when context requires disambiguation between in-process and external modifications.

• parse_<format>: Extracts structured data from formatted input (e.g., JSON, XML).

• prepare_<component>: Fully initializes component, including registration of handlers/extensions. Related: configure_<component> for settings application.

• probe_<resource>: Tests resource accessibility or status. Returns boolean indicating availability. Related: verify_<condition> for more thorough verification.

• produce_<object>: Creates new instance in process memory. For external resource creation, see create_<resource>.

• query_<resource>: Performs structured data retrieval with parameters or filters. Related: retrieve_<resource> for simpler data access.

• register_<reactor>: Adds event handler or callback to registry. Antonym: deregister_<reactor>.

• release_<resource>: Releases previously acquired shared resource. Antonym: acquire_<resource>.

• render_<template>: Produces output by combining template with data.

• report_<data>: Collates data from analyses or diverse sources into a structured or human-readable form.

• request_<action>: Initiates asynchronous operation, typically on remote service. Returns future or promise representing eventual completion.

• reserve_<resource>: Claims resource for future use. Related to schedule_<execution>; both use cancel_<future-or-reservation> as antonym.

• restore_<object>: Deserializes object from persistent storage. Related: save_<object> for serialization.

• retrieve_<resource>: Obtains copy of data from external resource. No release required. Related: query_<resource> for parameterized retrieval.

• save_<object>: Serializes object to persistent storage. Related: restore_<object> for deserialization.

• schedule_<execution>: Plans future execution of task or process. Related to reserve_<resource>; both use cancel_<future-or-reservation> as antonym.

• survey_<resource>: Lists or enumerates members of external resource collection.

• test_<assertion>: Verifies specific assertion about code behavior. Note: Only for use in test suites, not in public interfaces.

• transform_<data>: Changes data structure or format. Synonym: convert_<data>.

• update_<resource>: Modifies state of external resource. For in-process objects, consider modify_<object> when disambiguation is needed.

• validate_<object> [Python]: Returns object if valid, raises exception if invalid. [Rust]: Returns Result::Ok containing object if valid else Result::Err. Related: verify_<condition> which returns boolean if a condition is satisfied.

• verify_<condition>: Tests condition or state. Returns boolean. Related: 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

The project generally uses Latin-derived terms for both class and function names. This preference arises from:

• Prevalence of Latin-derived terms in computer science

• More precise technical meanings in Latin-derived terms

• Larger vocabulary of available terms

Germanic-derived and Greek-derived terms may be appropriate when maintaining linguistic consistency within:

• Related function names

• Class hierarchies

• Enum members

• Module-level names

Within individual names, maintain agreement between verbs and nouns:

• 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 from any linguistic derivation.

When in doubt, prefer Latin-derived terms as the project default.

Latin-to-Germanic Verb Mappings

The following table provides Germanic alternatives to Latin-derived verbs. These are provided primarily for reference and for cases where linguistic consistency with Germanic nouns is desired.

Latin-derived	Germanic-derived	Notes
access	get
acquire	grab	Common in technical phrases
activate	start
allocate	slot
assess	weigh	Is there a better synonym?
assert	swear	Is there a better synonym?
calculate	reckon
cancel	stop
configure	setup	Compound from “set up”
create	make
deactivate	stop
deallocate	free
delete	kill
deregister	unenroll	Germanic un- prefix pattern
disable	unswitch	Neologism; pairs with switch
discover	find
display	show
enable	switch	Pairs with unswitch
ensure	righten	Slightly archaic
examine	sniff	Informal but established in tech
filter	sift
intercept	catch
modify	change
parse	split
prepare	ready	Used as verb not adjective
probe	ping	From network terminology
produce	new	Verb; familiar to C++ programmers
query	ask
register	enroll
release	free
render	fillin / mold	Compound from “fill in”
report	tell
request	ask	Same as query mapping
reserve	earmark
restore	load	Common pair with dump
retrieve	fetch
save	dump	Common pair with load
schedule	handoff	Compound from “hand off”
survey	list
transform	shape	Avoids Latin re- prefix
update	freshen
validate	sound	Archaic but precise meaning
verify	truth	Used as verb: “to tell truth”