pkl-python 0.1.10__tar.gz → 0.1.12__tar.gz

{pkl-python-0.1.10 → pkl-python-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pkl-python
-Version: 0.1.10
+Version: 0.1.12
 Summary: Python library for Apple's PKL.
 Author-email: Jungwoo Yang <jwyang0213@gmail.com>
 License: MIT License
@@ -31,7 +31,7 @@ Project-URL: Source, https://github.com/jw-y/pkl
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: msgpack>=1.0.8
@@ -45,27 +45,24 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: tox; extra == "dev"
 
-# pkl-python - PKL Language Python Binding
-Python binding for [Apple's Pkl language](https://pkl-lang.org/index.html).
+> [!CAUTION]
+>
+> # THIS LIBRARY IS CURRENTLY PRE-RELEASE
+>
+> `pkl-python` is currently major version `v0`, and **breaking changes will happen** between versions.
 
-### Status
-* Evaluator API: fully functional
-* Code Generation: in development
-
-### TODO
-* [ ] (codgen) binary installation feature
-* [ ] (codgen) fix class order
-* [ ] (codgen) clean up code
+# pkl-python - Pkl Bindings for Python
+Python binding for [Apple's Pkl language](https://pkl-lang.org/index.html).
 
-## Installation
+## Getting Started
+### Installation
 
 ``` bash
 pip install pkl-python
 ```
 
-## Usage
 ### Basic Usage
-Here's how you can start using PKLL to load a PKL module:
+Here's how you can start using `pkl-python` to load a PKL module:
 
 ```python
 import pkl
@@ -74,60 +71,93 @@ config = pkl.load("path/to/pkl/example_module.pkl")
 print(config)
 ```
 
+### Status
+* Evaluator API: fully functional
+* Code Generation: in development
+
+### TODO
+* [ ] (codgen) pip binary installation
+* [ ] (codgen) fix class order
+* [ ] (codgen) clean up code
+
+
+## Usage
+
 ## Advanced Features
 For details on the parameters, refer [Message Passing API](https://pkl-lang.org/main/current/bindings-specification/message-passing-api.html).
 
 ```python
-from pkl import load
+import pkl
 
-# Advanced loading with custom environment and properties
-result = load(
-    "path/to/pkl/example_module.pkl"
-    env={"CUSTOM_ENV": "value"},
-    properties={"custom.property": "value"}
-)
-print(result)
+config = pkl.load("./tests/types.pkl")
+config = pkl.load("./tests/types.pkl", expr="datasize")
+config = pkl.load(None, module_text="a: Int = 1 + 1")
+config = pkl.load("./tests/types.pkl", debug=True)
 ```
 
-### Custom Handler
-It is possible to add custom resources or module handler:
+### Custom Readers
+It is possible to add module or resource or module readers:
 ```python
+from typing import List
+from dataclasses import dataclass
+
 import pkl
-from pkl.handler import (
-    ListResponse,
-    ReadModuleResponse,
-    ReadResourceResponse,
-    ResourcesHandler,
+from pkl import (
+    ModuleReader, ResourceReader, PathElement,
+    ModuleSource, PreconfiguredOptions, PklError,
 )
-from pkl.msgapi import ClientResourceReader
-
-class CustomModuleHandler(ResourcesHandler):
-    def list_response(self, uri: str) -> ListResponse:
-        return ListResponse(
-            pathElements=[{"name": "foo.pkl", "isDirectory": False}]
-        )
-
-    def read_response(self, uri: str) -> ReadResourceResponse:
-        return ReadModuleResponse(
-            contents="foo = 1",
-        )
-
-config = pkl.load(
-    "./tests/myModule.pkl",
-    allowedModules=["pkl:", "repl:", "file:", "customfs:"],
-    clientModuleReaders=[
-        {
-            "scheme": "customfs",
-            "hasHierarchicalUris": True,
-            "isGlobbable": True,
-            "isLocal": True,
-        }
-    ],
-    debug=True,
-    module_handler=CustomModuleHandler(),
+
+class TestModuleReader(ModuleReader):
+    def read(self, url) -> str:
+        return "foo = 1"
+
+    def list_elements(self, url: str) -> List[PathElement]:
+        return [PathElement("foo.pkl", False)]
+
+opts = PreconfiguredOptions(
+    moduleReaders=[TestModuleReader("customfs", True, True, True)]
 )
+opts.allowedModules.append("customfs:")
+config = pkl.load("./tests/myModule.pkl", evaluator_options=opts)
 ```
 
+## Appendix
+
+### Type Mappings
+
+While in pre-release they are subject to change.
+
+| Pkl type         | TypeScript type            |
+| ---------------- | -------------------------- |
+| Null             | `None`                     |
+| Boolean          | `bool`                     |
+| String           | `str`                      |
+| Int              | `int`                      |
+| Int8             | `int`                      |
+| Int16            | `int`                      |
+| Int32            | `int`                      |
+| UInt             | `int`                      |
+| UInt8            | `int`                      |
+| UInt16           | `int`                      |
+| UInt32           | `int`                      |
+| Float            | `float`                    |
+| Number           | `float`                    |
+| List             | `list`                     |
+| Listing          | `list`                     |
+| Map              | `dict`                     |
+| Mapping          | `dict`                     |
+| Set              | `set`                      |
+| Pair             | `pkl.Pair`                 |
+| Dynamic          | `dataclasses.dataclass`    |
+| DataSize         | `pkl.DataSize`             |
+| Duration         | `pkl.Duration`             |
+| IntSeq           | `pkl.IntSeq`               |
+| Class            | `dataclasses.dataclass`    |
+| TypeAlias        | `typing`                   |
+| Any              | `typing.Any`               |
+| Unions (A\|B\|C) | `typing.Union[A\|B\|C]`    |
+| Regex            | `pkl.Regex`                |
+
 ## Contributing
 Contributions are welcome! If you'd like to contribute, please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
 

pkl-python-0.1.12/README.md

@@ -0,0 +1,121 @@
+> [!CAUTION]
+>
+> # THIS LIBRARY IS CURRENTLY PRE-RELEASE
+>
+> `pkl-python` is currently major version `v0`, and **breaking changes will happen** between versions.
+
+# pkl-python - Pkl Bindings for Python
+Python binding for [Apple's Pkl language](https://pkl-lang.org/index.html).
+
+## Getting Started
+### Installation
+
+``` bash
+pip install pkl-python
+```
+
+### Basic Usage
+Here's how you can start using `pkl-python` to load a PKL module:
+
+```python
+import pkl
+
+config = pkl.load("path/to/pkl/example_module.pkl")
+print(config)
+```
+
+### Status
+* Evaluator API: fully functional
+* Code Generation: in development
+
+### TODO
+* [ ] (codgen) pip binary installation
+* [ ] (codgen) fix class order
+* [ ] (codgen) clean up code
+
+
+## Usage
+
+## Advanced Features
+For details on the parameters, refer [Message Passing API](https://pkl-lang.org/main/current/bindings-specification/message-passing-api.html).
+
+```python
+import pkl
+
+config = pkl.load("./tests/types.pkl")
+config = pkl.load("./tests/types.pkl", expr="datasize")
+config = pkl.load(None, module_text="a: Int = 1 + 1")
+config = pkl.load("./tests/types.pkl", debug=True)
+```
+
+### Custom Readers
+It is possible to add module or resource or module readers:
+```python
+from typing import List
+from dataclasses import dataclass
+
+import pkl
+from pkl import (
+    ModuleReader, ResourceReader, PathElement,
+    ModuleSource, PreconfiguredOptions, PklError,
+)
+
+class TestModuleReader(ModuleReader):
+    def read(self, url) -> str:
+        return "foo = 1"
+
+    def list_elements(self, url: str) -> List[PathElement]:
+        return [PathElement("foo.pkl", False)]
+
+opts = PreconfiguredOptions(
+    moduleReaders=[TestModuleReader("customfs", True, True, True)]
+)
+opts.allowedModules.append("customfs:")
+config = pkl.load("./tests/myModule.pkl", evaluator_options=opts)
+```
+
+## Appendix
+
+### Type Mappings
+
+While in pre-release they are subject to change.
+
+| Pkl type         | TypeScript type            |
+| ---------------- | -------------------------- |
+| Null             | `None`                     |
+| Boolean          | `bool`                     |
+| String           | `str`                      |
+| Int              | `int`                      |
+| Int8             | `int`                      |
+| Int16            | `int`                      |
+| Int32            | `int`                      |
+| UInt             | `int`                      |
+| UInt8            | `int`                      |
+| UInt16           | `int`                      |
+| UInt32           | `int`                      |
+| Float            | `float`                    |
+| Number           | `float`                    |
+| List             | `list`                     |
+| Listing          | `list`                     |
+| Map              | `dict`                     |
+| Mapping          | `dict`                     |
+| Set              | `set`                      |
+| Pair             | `pkl.Pair`                 |
+| Dynamic          | `dataclasses.dataclass`    |
+| DataSize         | `pkl.DataSize`             |
+| Duration         | `pkl.Duration`             |
+| IntSeq           | `pkl.IntSeq`               |
+| Class            | `dataclasses.dataclass`    |
+| TypeAlias        | `typing`                   |
+| Any              | `typing.Any`               |
+| Unions (A\|B\|C) | `typing.Union[A\|B\|C]`    |
+| Regex            | `pkl.Regex`                |
+
+## Contributing
+Contributions are welcome! If you'd like to contribute, please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+PKL is released under the MIT License. See the LICENSE file for more details.
+
+## Contact
+For support or to contribute, please contact jwyang0213@gmail.com or visit our GitHub repository to report issues or submit pull requests.

pkl-python-0.1.12/pkl/VERSION

@@ -0,0 +1 @@
+0.1.12

pkl-python-0.1.12/pkl/__init__.py

@@ -0,0 +1,118 @@
+import os
+from pathlib import Path
+from typing import Optional, Union
+from urllib.parse import ParseResult, urlparse
+
+from pkl.evaluator_manager import Evaluator, EvaluatorManager
+from pkl.evaluator_options import EvaluatorOptions, PreconfiguredOptions
+from pkl.parser import DataSize, Duration, IntSeq, Pair, Parser, Regex
+from pkl.reader import ModuleReader, PathElement, ResourceReader
+from pkl.utils import ModuleSource, PklBugError, PklError
+
+# get version
+with open(os.path.join(os.path.dirname(__file__), "VERSION"), "r") as _f:
+    __version__ = _f.read().strip()
+
+
+class PklDefaultType:
+    def __repr__(self):
+        return "<PklDefault>"
+
+
+PKL_DEFAULT = PklDefaultType()
+
+
+def _search_project_dir(module_path: str) -> str:
+    cur_path = Path(module_path).parent.absolute()
+    while not (cur_path / "PklProject").exists():
+        cur_path = cur_path.parent
+        if str(cur_path) == "/":
+            break
+
+    if str(cur_path) == "/":
+        cur_path = Path(module_path).parent
+    return str(cur_path.absolute())
+
+
+def load(
+    module_uri: Union[str, Path],
+    *,
+    module_text: Optional[str] = None,
+    expr: Optional[str] = None,
+    project_dir: str = PKL_DEFAULT,
+    evaluator_options: EvaluatorOptions = PreconfiguredOptions(),
+    parser=None,
+    debug=False,
+    **kwargs,
+):
+    """
+    Loads and evaluates a Pkl module or expression with specified parameters and customization options.
+
+    Args:
+        module_uri (str): The absolute URI of the module to be loaded.
+        module_text (Optional[str], None): Optionally, the content of the module to be loaded.
+            If None, the module is loaded from the specified URI.
+        expr (Optional[str], None): Optionally, a Pkl expression to be evaluated
+            within the loaded module. If None, the entire module is evaluated.
+        project_dir (str, PKL_DEFAULT): The project directory to use for this command.
+            By default, searches up from the working directory for a PklProject file.
+        evaluator_options (EvaluatorOptions, PreconfiguredOptions()):
+            extra options for evaluator
+        parser: A specific parser to be used for parsing the module.
+            If None, a default parser is used.
+        debug (bool, False): Enable debugging mode for additional output and diagnostics.
+        **kwargs: Additional keyword arguments for extensibility and future use.
+
+    Returns:
+        The result of the module or expression evaluation, depending on the inputs and configuration.
+
+    This function provides a flexible interface for loading and evaluating Pkl modules
+    with a variety of customization options, including custom module and resource readers,
+    environmental configurations, and support for complex project dependencies.
+    """
+
+    parsed = urlparse(str(module_uri))
+
+    def is_uri(_uri: ParseResult):
+        return bool(_uri.scheme) and (bool(_uri.netloc) or bool(_uri.path))
+
+    if module_text:
+        source = ModuleSource.from_text(module_text)
+    elif is_uri(parsed):
+        source = ModuleSource.from_uri(module_uri)
+    else:
+        source = ModuleSource.from_path(module_uri)
+
+    if project_dir is PKL_DEFAULT:
+        project_dir = _search_project_dir(str(module_uri))
+
+    with EvaluatorManager(debug=debug) as manager:
+        if (Path(project_dir) / "PklProject").exists():
+            evaluator = manager.new_project_evaluator(
+                project_dir, evaluator_options, parser=parser
+            )
+        else:
+            evaluator = manager.new_evaluator(evaluator_options, parser=parser)
+        config = evaluator.evaluate_expression(source, expr)
+    return config
+
+
+__all__ = [
+    "load",
+    "Evaluator",
+    "EvaluatorManager",
+    "EvaluatorOptions",
+    "PreconfiguredOptions",
+    "ModuleReader",
+    "ResourceReader",
+    "PathElement",
+    "Parser",
+    "ModuleSource",
+    "PklError",
+    "PklBugError",
+    "Duration",
+    "DataSize",
+    "Pair",
+    "IntSeq",
+    "Regex",
+]