Metadata-Version: 2.1
Name: myrrh_core_exts
Version: 0.1.0
Summary: This package enables extension management.
Author-email: PyAnjel7 <PyAnjel7@gmail.com>
License: GNU General Public License v3.0 or later
Keywords: baseline:Earendel.
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md

# Readme

## About myrrh_core_exts

This package is part of the Myrrh project.

This package enables extension management.
It aims to simplify the management and registration of myrrh extensions by using URI.


Baseline:earendel.

## Requirements

* Python >= 3.12

## Installation

To install myrrh-exts, simply execute:

```shell
$ pip install myrrh-core-exts
```

## Getting Started


Myrrh core extension package is based on URI, predefined interfaces, and the standard entry point mechanism. 


### How to define a myrrh extension?


First define your extension by creating a protocol class, a session class, and an entry point class.

Declare the extension using the project configuration file, with the extension URI scheme being the group name and the extension URI path being the entry point name.


### Sample implementation of extension.


myexts/hello.py
```python

from myrrh.core.exts.interfaces import IExtSession, uri_rd
from myrrh.core.exts.protocol import StdExtSession, MyrrhExtBase
from myrrh.core.exts.misc import URI
from myrrh.core.exts.errors import InvalidPath

class IEchoProtocol(IExtProtocol):

    @uri_rd
    @abc.abstractmethod
    def hello(self): ...

class HelloSession(StdExtSession, IEchoProtocol):

    def __init__(self, path):
        super().__init__(IEchoProtocol)

        self.path = path

    def hello(self, myname):
        return f"Hello {myname} from {self.path}"

class Hello(MyrrhExtBase):
    
    def open(self, uri: str, *, req = None) -> HelloSession:
        path = URI(uri).path.removeprefix(self._path)  
        return HelloSession(path)
        
    def extend(self, path: str, _obj):
        raise InvalidPath(path)

```

myexts/pyproject.toml
```
...

[myproject.exts]
/my/ext/path = "myext.hello:Hello"

...

```

myexts/main.py
```python
from myrrh.core.exts.registry import Registry

Register().loads("myproject.exts")

with Registry().open("myproject.core.exts:/my/ext/path?=hello&myname=PyAnjel7") as f:
    open_resp = f.read(1)

c = Registry().client("myproject.core.exts:/my/ext/path")
with c.open():
    client_resp = c.hello('Pyanjel7')

assert open_resp == client_resp
```

## Command line tool

usage: mexts [-h] {push,get,list} uri

positional arguments:
  {push,get,list}
  uri

options:
  -h, --help       show this help message and exit

```shell
> mexts get "myrrh.core.exts:/registry?=loaded"
[['myrrh.core.exts:/registry']]
> mexts get "myrrh.core.exts:/registry?=__proto__"
[['findall', 'loaded']]
```

## License

GNU General Public License v3.0 or later
