Auto discover Domain.root_path (#519)

Removes the need for users to pass `__file__` when instantiating a Domain, while still allowing an explicit override.

Environments supported:

- Standard Python execution (scripts, console entry-points)
- Jupyter / IPython notebooks
- REPL / interactive shell
- Frozen / zipapp / PyInstaller builds

Also:
- Updated the Domain initialization across various documentation files and test cases to use the new parameter format.
- Changed instances of `Domain(__file__, "name")` to `Domain(name="name")` for consistency and clarity.

Fixes #514

Author: subhashb

README.md

@@ -28,7 +28,7 @@ Protean officially supports Python 3.11+.
 from protean import Domain
 from protean.fields import String, Text
 
-domain = Domain(__file__, "Publishing")
+domain = Domain(name="Publishing")
 
 @domain.aggregate
 class Post:

docs/guides/compose-a-domain/index.md

@@ -6,28 +6,28 @@ In Protean, the Domain serves as the central composition root of your applicatio
 
 The Domain acts as a composition root, bringing together all the essential components of your application. It provides a centralized location where all elements are registered, configured, and made available for use throughout your application. This centralization simplifies dependency management and promotes a more maintainable architecture.
 
-## Key Responsibilities
+### Key Responsibilities
 
-### Element Management
+#### Element Management
 
 The Domain maintains a registry of all domain elements, including entities, value objects, repositories, services, and other components. This registry serves as a catalog that makes these elements discoverable and accessible throughout your application.
 
-### Configuration Storage
+#### Configuration Storage
 
 Your Domain stores configuration settings that define how your application behaves. These settings can include database connection parameters, feature flags, environment-specific values, and other application-wide settings. Read more at [Configuration](../configuration.md).
 
-### Adapter Activation
+#### Adapter Activation
 
 The Domain manages the lifecycle of adapters, which are components that connect your application to external systems and services. This includes activating the appropriate adapters based on your configuration and ensuring they are properly initialized.
 
-### Automatic Element Collection
+#### Automatic Element Collection
 
 Protean's Domain leverages Python decorators to automatically collect and register domain elements. By simply applying the appropriate decorator to your classes, they are automatically discovered and registered with the Domain during initialization.
 
 ```python
 from protean import Domain
 
-domain = Domain(__file__)
+domain = Domain()
 ...
 
 @domain.aggregage
@@ -37,11 +37,100 @@ class User:
 
 This declarative approach reduces boilerplate code and makes your domain model more expressive and maintainable.
 
+## Parameters
+
+The `Domain` constructor accepts several parameters that control how the domain is initialized and configured:
+
+### `root_path`
+
+Optional. Defaults to `None`.
+
+The path to the folder containing the domain file. This parameter is optional and follows a resolution priority:
+
+1. Explicit `root_path` parameter if provided
+2. `DOMAIN_ROOT_PATH` environment variable if set
+3. Auto-detection of caller's file location
+4. Current working directory as last resort
+
+The `root_path` is used for finding configuration files and traversing domain files.
+
+```python
+# Explicit root path
+domain = Domain(root_path="/path/to/domain")
+
+# Using environment variable
+# export DOMAIN_ROOT_PATH="/path/to/domain"
+domain = Domain()  # Will use DOMAIN_ROOT_PATH
+
+# Auto-detection (uses the directory of the file where Domain is instantiated)
+domain = Domain()
+```
+
+This is handled even under various execution contexts:
+
+- Standard Python scripts
+- Jupyter/IPython notebooks
+- REPL/interactive shell
+- Frozen/PyInstaller applications
+
+### `name`
+
+The name of the domain. 
+
+Optional and defaults to the module name where the domain is instantiated.
+
+The domain name is used in various contexts, including event type construction and logging.
+
+```python
+# Explicit name
+domain = Domain(name="ecommerce")
+
+# Default name (uses module name)
+domain = Domain()  # If in module 'my_app', name will be 'my_app'
+```
+
+### `config`
+
+An optional configuration dictionary that overrides the default configuration and any configuration loaded from files.
+
+If not provided, configuration is loaded from `.domain.toml`, `domain.toml`, or `pyproject.toml` files in the domain folder or its parent directories.
+
+```python
+# Explicit configuration
+domain = Domain(config={
+    "identity_strategy": "UUID",
+    "databases": {
+        "default": {"provider": "postgres", "url": "postgresql://user:pass@localhost/db"}
+    }
+})
+
+# Default configuration (loads from TOML files if available)
+domain = Domain()
+```
+
+Refer to [Configuration](../configuration.md) to understand configuration file structure and parameters.
+
+### `identity_function`
+
+An optional function to generate identities for domain objects. This parameter is required when the `identity_strategy` in configuration is set to `FUNCTION`.
+
+```python
+# Custom identity function
+def generate_id():
+    # Custom ID generation logic
+    return "custom-id-" + str(random.randint(1000, 9999))
+
+# Using custom identity function
+domain = Domain(
+    config={"identity_strategy": "FUNCTION"},
+    identity_function=generate_id
+)
+```
+
 ## In This Section
 
 - [Register Elements](./register-elements.md) - Explore methods for registering domain elements
 - [Initialize Domain](./initialize-domain.md) - Understand how to set up and initialize a new domain
 - [Element Decorators](./element-decorators.md) - Learn about using decorators to automatically register domain elements
 - [Activate Domain](./activate-domain.md) - Understand how to activate a domain and its components
 - [When to Compose a Domain](./when-to-compose.md) - Learn about the appropriate timing and scenarios for composing a domain
-

docs/guides/compose-a-domain/initialize-domain.md

@@ -6,9 +6,11 @@ The domain is initialized by calling the `init` method.
 domain.init()
 ```
 
+## `Domain.init()`
+
 A call to `init` does the following:
 
-## 1. Traverse the domain model
+### 1. Traverse the domain model
 
 By default, Protean traverses the directory structure under the domain file
 to discover domain elements. You can control this behavior with the `traverse`
@@ -22,7 +24,7 @@ If you choose to not traverse, Protean will not be able to detect domain
 elements automatically. ***You are responsible for registering each element
 with the domain explicitly***.
 
-## 2. Construct the object graph
+### 2. Construct the object graph
 
 Protean constructs a graph of all elements registered with a domain and
 exposes them in a registry.
@@ -31,7 +33,7 @@ exposes them in a registry.
 {! docs_src/guides/composing-a-domain/016.py !}
 ```
 
-## 3. Initialize dependencies
+### 3. Initialize dependencies
 
 Calling `domain.init()` establishes connectivity with the underlying infra,
 testing access, and making them available for use by the rest of the system. 
@@ -52,7 +54,7 @@ makes it available for domain elements for further use.
 Refer to [Configuration handling](../configuration.md) to understand the different ways to configure
 the domain.
 
-## 4. Validate Domain Model
+### 4. Validate Domain Model
 
 In the final part of domain initialization, Protean performs additional setup
 tasks on domain elements and also conducts various checks to ensure the domain
@@ -61,17 +63,18 @@ model is specified correctly.
 Examples of checks include:
 
 1. Resolving references that were specified as Strings, like:
+
 ```python
 @domain.entity(part_of="User")
 class Account:
     ...
 ```
 
-2. Setting up Aggregate clusters and their shared settings. The object graph
+1. Setting up Aggregate clusters and their shared settings. The object graph
 constructed earlier is used to homogenize settings across all elements under
 an aggregate, like the stream category and database provider.
 
-3. Constructing a map of command and event types to reference when processing
+1. Constructing a map of command and event types to reference when processing
 incoming messages later.
 
-4. Various checks and validations to ensure the domain structure is valid.
+1. Various checks and validations to ensure the domain structure is valid.

docs/guides/configuration.md

@@ -2,16 +2,25 @@
 
 Protean's configuration is managed through the Domain object, which can be configured in multiple ways:
 
-1. **Direct Configuration**: Pass a configuration dictionary when initializing the Domain object:
+## Direct Configuration
+
+Pass a configuration dictionary when initializing the Domain object:
+
    ```python
    domain = Domain(config={'debug': True, 'testing': True})
    ```
 
-2. **Configuration Files**: Place configuration in a TOML file in your project directory or up to two levels of parent directories. Protean searches for configuration files in the following order:
+## Configuration Files
+
+Place configuration can be supplied in a TOML file in your project directory or up to two levels of parent directories.
+
+Protean searches for configuration files in the following order:
+
+1. `.domain.toml`
+1. `domain.toml`
+1. `pyproject.toml` (under the `[tool.protean]` section)
 
-   - `.domain.toml`
-   - `domain.toml` 
-   - `pyproject.toml` (under the `[tool.protean]` section)
+### Generating a new configuration file
 
 When initializing a new Protean application using the [`new`](./cli/new.md) command, a `domain.toml` configuration file is automatically generated with sensible defaults.
 
@@ -88,7 +97,7 @@ foo = "quux"
 
 Specifies if the application is running in debug mode.
 
-***Do not enable debug mode when deploying in production.***
+*Do not enable debug mode when deploying in production.*
 
 Default: `False`
 
@@ -112,7 +121,7 @@ You can generate a secret key with the following command:
 c4bf0121035265bf44657217c33a7d041fe9e505961fc7da5d976aa0eaf5cf94
 ```
 
-***Do not reveal the secret key when posting questions or committing code.***
+*Do not reveal your secret key when posting questions or committing code.*
 
 ### `identity_strategy`
 
@@ -272,7 +281,7 @@ FOO = "bar"
 ```
 
 ```shell hl_lines="3-4 6-7"
-In [1]: domain = Domain(__file__)
+In [1]: domain = Domain()
 
 In [2]: domain.config["custom"]["FOO"]
 Out[2]: 'bar'

docs_src/adapters/001.py

@@ -1,6 +1,6 @@
 from protean import Domain
 
-domain = Domain(__file__)
+domain = Domain()
 
 # Non-existent database
 domain.config["databases"]["default"] = {

docs_src/adapters/database/postgresql/001.py

@@ -4,7 +4,7 @@
 from protean.adapters.repository.sqlalchemy import SqlalchemyModel
 from protean.fields import Integer, String
 
-domain = Domain(__file__)
+domain = Domain()
 domain.config["databases"]["default"] = {
     "provider": "postgresql",
     "database_uri": "postgresql://postgres:postgres@localhost:5432/postgres",

docs_src/guides/change_state_001.py

@@ -1,7 +1,7 @@
 from protean import Domain
 from protean.fields import String
 
-domain = Domain(__file__)
+domain = Domain()
 
 
 @domain.aggregate

docs_src/guides/change_state_002.py

@@ -1,7 +1,7 @@
 from protean import Domain
 from protean.fields import Float, HasMany, String, Text
 
-domain = Domain(__file__)
+domain = Domain()
 
 
 @domain.aggregate

docs_src/guides/change_state_003.py

@@ -1,7 +1,7 @@
 from protean import Domain
 from protean.fields import Boolean, Identifier, String, Text
 
-domain = Domain(__file__)
+domain = Domain()
 
 
 @domain.aggregate

docs_src/guides/change_state_004.py

@@ -1,7 +1,7 @@
 from protean import Domain
 from protean.fields import Integer, String
 
-domain = Domain(__file__)
+domain = Domain()
 
 
 @domain.aggregate