pkl-python 0.0.0__tar.gz

pkl-python-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jungwoo Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pkl-python-0.0.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.1
+Name: pkl-python
+Version: 0.0.0
+Summary: Python library for Apple's PKL.
+Author-email: Jungwoo Yang <jwyang0213@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Jungwoo Yang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/jw-y/pkl
+Project-URL: Bug Reports, https://github.com/jw-y/pkl/issues
+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.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msgpack>=1.0.8
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+
+> [!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
+* [x] (codgen) fix class order
+* [ ] (codgen) pip binary installation
+* [ ] (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.0.0/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
+* [x] (codgen) fix class order
+* [ ] (codgen) pip binary installation
+* [ ] (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.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pkl-python"
+dynamic = ["version"]
+description = "Python library for Apple's PKL."
+authors = [
+    { name = "Jungwoo Yang", email = "jwyang0213@gmail.com" },
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "msgpack >= 1.0.8",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+#include = ["pkl", "pkl_gen_python.py"]
+
+[tool.setuptools.dynamic]
+version = {file = "pkl/VERSION"}
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit",
+    "black",
+    "isort",
+    "mypy",
+    "pylint",
+    "pytest",
+    "pytest-cov",
+    "tox",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/jw-y/pkl"
+"Bug Reports" = "https://github.com/jw-y/pkl/issues"
+"Source" = "https://github.com/jw-y/pkl"
+
+[project.scripts]
+pkl-gen-python = "pkl_gen_python:main"
+
+[tool.twine]
+repository = "pypi"
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+force-exclude = 'codegen/snippet-tests/output/'
+
+[tool.isort]
+profile = "black"
+skip = ["codegen/snippet-tests/output/*"]
+
+[tool.autoflake]
+exclude = ["codegen/snippet-tests/output/*"]
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"

pkl-python-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pkl-python-0.0.0/setup.py

@@ -0,0 +1,74 @@
+import os
+import platform
+import stat
+from pathlib import Path
+
+import setuptools
+from setuptools.command.install import install
+
+BINARIES = {
+    ("darwin", "64bit"): "pkl-macos-amd64",
+    ("darwin", "aarch64"): "pkl-macos-aarch64",
+    ("linux", "64bit"): "pkl-linux-amd64",
+    ("linux", "aarch64"): "pkl-linux-aarch64",
+    ("linux", "64bit", "alpine"): "pkl-alpine-linux-amd64",
+}
+PKL_VERSION = "0.25.3"
+BASE_PATH = "https://github.com/apple/pkl/releases/download/"
+
+
+def detect_system():
+    os_name = platform.system().lower()
+    arch, _ = platform.architecture()
+    return os_name, arch
+
+
+def is_alpine_linux():
+    return os.path.isfile("/etc/alpine-release")
+
+
+def download_binary(file, target_fp):
+    import requests
+
+    url = BASE_PATH + PKL_VERSION + "/" + file
+    response = requests.get(url)
+    with open(target_fp, "wb") as f:
+        f.write(response.content)
+
+
+def get_binary_path():
+    os_name, arch = detect_system()
+    if os_name == "linux" and is_alpine_linux():
+        os_name = "alpine"
+    binary_key = (os_name, arch)
+    if binary_key == ("linux", "64bit") and is_alpine_linux():
+        binary_key += ("alpine",)
+    bin_file = BINARIES.get(binary_key)
+
+    if bin_file is None:
+        raise OSError("No compatible binary found for your system.")
+
+    bin_parent_path = (Path("~/.pkl/bin/") / PKL_VERSION).expanduser()
+    binary_path = bin_parent_path / bin_file
+
+    if not binary_path.exists():
+        binary_path.parent.mkdir(exist_ok=True, parents=True)
+        download_binary(bin_file, binary_path)
+
+    current_permissions = os.stat(binary_path).st_mode
+    new_permissions = current_permissions | stat.S_IXUSR
+    os.chmod(binary_path, new_permissions)
+
+    return binary_path
+
+
+class CustomInstallCommand(install):
+    def run(self):
+        get_binary_path()
+        install.run(self)
+
+
+setuptools.setup(
+    cmdclass={"install": CustomInstallCommand},
+    setup_requires=["requests"],
+)

pkl-python-0.0.0/src/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",
+]