Merge pull request #95 from Exabyte-io/feature/SOF-7755

Feature/SOF-7755 Add Python codebase

Author: VsevolodX

README.md

@@ -22,12 +22,19 @@ For usage within a JavaScript project:
 npm install @mat3ra/ade
 ```
 
+For usage within a Python project:
+
+```bash
+pip install mat3ra-ade
+```
+
 For development:
 
 ```bash
 git clone https://github.com/Exabyte-io/ade.git
 ```
 
+
 ## Contributions
 
 This repository is an [open-source](LICENSE.md) work-in-progress and we welcome contributions.
@@ -39,6 +46,7 @@ See [ESSE](https://github.com/Exabyte-io/esse) for additional context regarding
 
 Useful commands for development:
 
+### JavaScript/TypeScript
 ```bash
 # run linter without persistence
 npm run lint
@@ -62,6 +70,20 @@ npm run test:coverage:check
 npm run test:coverage:html
 ```
 
+### Python
+```bash
+# run linter
+python -m black src/py/mat3ra/ade/ tests/py/
+python -m ruff check src/py/mat3ra/ade/ tests/py/
+python -m isort src/py/mat3ra/ade/ tests/py/
+
+# run tests
+python -m pytest tests/py/
+
+# run tests with coverage
+python -m pytest tests/py/ --cov=mat3ra.ade --cov-report=html
+```
+
 ## Development: Code/Test Coverage
 
 This project includes comprehensive code coverage reporting with multiple viewing options:

pyproject.toml

@@ -20,6 +20,10 @@ classifiers = [
 ]
 dependencies = [
     "numpy",
+    "pydantic>=2.0",
+    "mat3ra-esse",
+    "mat3ra-code",
+    "mat3ra-utils[extra]"
 ]
 
 [project.optional-dependencies]
@@ -35,6 +39,8 @@ tests = [
     "coverage[toml]>=5.3",
     "pytest",
     "pytest-cov",
+    "mat3ra-esse",
+    "mat3ra-utils"
 ]
 all = [
     "mat3ra-ade[tests]",

src/py/mat3ra/__init__.py

@@ -1,2 +1 @@
-"""mat3ra namespace package."""
-
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

src/py/mat3ra/ade/__init__.py

@@ -1,6 +1,22 @@
-import numpy as np
-
-
-def get_length(vec: np.ndarray) -> float:
-    return float(np.linalg.norm(vec))
+from mat3ra.ade.application import Application
+from mat3ra.ade.executable import Executable
+from mat3ra.ade.flavor import Flavor, FlavorInput
+from mat3ra.ade.template import (
+    ContextProvider,
+    Template,
+)
+from mat3ra.ade.context.json_schema_data_provider import (
+    JSONSchemaDataProvider,
+)
+from mat3ra.ade.context.jinja_context_provider import JinjaContextProvider
 
+__all__ = [
+    "Application",
+    "Executable",
+    "Flavor",
+    "FlavorInput",
+    "Template",
+    "ContextProvider",
+    "JinjaContextProvider",
+    "JSONSchemaDataProvider",
+]

src/py/mat3ra/ade/application.py

@@ -0,0 +1,28 @@
+from mat3ra.code.entity import InMemoryEntitySnakeCase
+from mat3ra.esse.models.software.application import ApplicationSchemaBase
+
+
+class Application(ApplicationSchemaBase, InMemoryEntitySnakeCase):
+    """
+    Application class representing a software application.
+
+    Attributes:
+        name: Application name (required)
+        version: Application version
+        build: Application build
+        shortName: Short name of the application
+        summary: Application's short description
+        hasAdvancedComputeOptions: Whether advanced compute options are present
+        isLicensed: Whether licensing is present
+        isDefault: Identifies that entity is defaultable
+        schemaVersion: Entity's schema version
+    """
+
+    @property
+    def is_using_material(self) -> bool:
+        material_using_applications = ["vasp", "nwchem", "espresso"]
+        return self.name in material_using_applications
+
+    def get_short_name(self) -> str:
+        return self.shortName if self.shortName else self.name
+

src/py/mat3ra/ade/context/__init__.py

@@ -0,0 +1,98 @@
+from typing import Any, Dict, Optional
+
+from mat3ra.code.entity import InMemoryEntitySnakeCase
+from mat3ra.esse.models.context_provider import ContextProviderSchema
+
+
+class ContextProvider(ContextProviderSchema, InMemoryEntitySnakeCase):
+    """
+    Context provider for a template.
+
+    Attributes:
+        name: The name of this item (required)
+        domain: Domain of the context provider
+        entityName: Entity name associated with the context provider
+        data: Data object for the context provider
+        extraData: Additional data object for the context provider
+        isEdited: Flag indicating if the context provider has been edited
+        context: Context object for the context provider
+    """
+
+    @property
+    def name_str(self) -> str:
+        return self.name.value if hasattr(self.name, 'value') else str(self.name)
+
+    @property
+    def extra_data_key(self) -> str:
+        return f"{self.name_str}ExtraData"
+
+    @property
+    def is_edited_key(self) -> str:
+        return f"is{self.name_str}Edited"
+
+    @property
+    def is_unit_context_provider(self) -> bool:
+        return self.entityName == "unit"
+
+    @property
+    def is_subworkflow_context_provider(self) -> bool:
+        return self.entityName == "subworkflow"
+
+    def _get_data_from_context(self, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        if not context:
+            return {}
+        data = context.get(self.name_str)
+        is_edited = context.get(self.is_edited_key)
+        extra_data = context.get(self.extra_data_key)
+        result = {}
+        if data is not None:
+            result["data"] = data
+        if is_edited is not None:
+            result["isEdited"] = is_edited
+        if extra_data is not None:
+            result["extraData"] = extra_data
+        return result
+
+    def _get_effective_data(self, context: Optional[Dict[str, Any]] = None) -> Any:
+        context_data = self._get_data_from_context(context or self.context)
+        return context_data.get("data", self.data)
+
+    def _get_effective_is_edited(self, context: Optional[Dict[str, Any]] = None) -> bool:
+        context_data = self._get_data_from_context(context or self.context)
+        return context_data.get("isEdited", self.isEdited)
+
+    def _get_effective_extra_data(self, context: Optional[Dict[str, Any]] = None) -> Optional[Any]:
+        context_data = self._get_data_from_context(context or self.context)
+        return context_data.get("extraData", self.extraData)
+
+    def yield_data(self, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        data = self._get_effective_data(context)
+        is_edited = self._get_effective_is_edited(context)
+        extra_data = self._get_effective_extra_data(context)
+        result = {
+            self.name_str: data,
+            self.is_edited_key: is_edited,
+        }
+        if extra_data:
+            result[self.extra_data_key] = extra_data
+        return result
+
+    def yield_data_for_rendering(self, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self.yield_data(context)
+
+    def merge_context_data(self, result: Dict[str, Any], provider_context: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Merge this provider's rendering context data into result dictionary.
+        Merges context keys if they are objects, otherwise overrides them.
+
+        Args:
+            result: Dictionary to merge into (modified in place)
+            provider_context: Optional external context to override provider's internal data
+        """
+        context = self.yield_data_for_rendering(provider_context)
+        for key, value in context.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = {**result[key], **value}
+            else:
+                result[key] = value
+

src/py/mat3ra/ade/context/context_provider.py

@@ -0,0 +1,9 @@
+from pydantic import Field
+
+from .context_provider import ContextProvider
+
+
+class JinjaContextProvider(ContextProvider):
+    is_using_jinja_variables: bool = Field(
+        default=False, description="Whether this provider uses Jinja variables"
+    )

src/py/mat3ra/ade/context/jinja_context_provider.py

@@ -0,0 +1,9 @@
+from typing import Optional, Dict, Any
+
+from pydantic import Field
+
+from .jinja_context_provider import JinjaContextProvider
+
+
+class JSONSchemaDataProvider(JinjaContextProvider):
+    json_schema: Optional[Dict[str, Any]] = Field(default=None, description="JSON schema for this provider")

src/py/mat3ra/ade/context/json_schema_data_provider.py

@@ -0,0 +1,21 @@
+from mat3ra.code.entity import InMemoryEntitySnakeCase
+from mat3ra.esse.models.software.executable import ExecutableSchema
+
+
+class Executable(ExecutableSchema, InMemoryEntitySnakeCase):
+    """
+    Executable class representing an executable of an application.
+
+    Attributes:
+        name: The name of the executable (required)
+        applicationId: IDs of the application this executable belongs to
+        hasAdvancedComputeOptions: Whether advanced compute options are present
+        isDefault: Identifies that entity is defaultable
+        schemaVersion: Entity's schema version
+        preProcessors: Names of the pre-processors for this calculation
+        postProcessors: Names of the post-processors for this calculation
+        monitors: Names of the monitors for this calculation
+        results: Names of the results for this calculation
+    """
+
+    pass