yamlstar 0.1.7__py3-none-win_amd64.whl

yamlstar/__init__.py

@@ -0,0 +1,215 @@
+# Copyright 2024 yaml.org
+# MIT License
+
+"""
+Python binding/API for the libyamlstar shared library.
+
+This module provides a Python interface to YAMLStar, a pure YAML 1.2 loader.
+The YAMLStar class has methods for loading YAML documents and converting
+them to Python objects.
+"""
+
+# Version matching the yamlstar shared library
+yamlstar_version = '0.1.7'
+
+import os
+import sys
+import ctypes
+import json
+
+# Require Python 3.6 or greater:
+assert sys.version_info >= (3, 6), \
+  "Python 3.6 or greater required for 'yamlstar'."
+
+def find_libyamlstar():
+  """Find libyamlstar shared library. Returns (path, backend)."""
+  if sys.platform == 'linux':
+    so = 'so'
+  elif sys.platform == 'darwin':
+    so = 'dylib'
+  elif sys.platform == 'win32':
+    so = 'dll'
+  else:
+    raise Exception(
+      "Unsupported platform '%s' for yamlstar." % sys.platform)
+
+  # Use the platform library path, plus package and common install locations.
+  if sys.platform == 'win32':
+    library_path = os.environ.get('PATH')
+    library_paths = library_path.split(';') if library_path else []
+  else:
+    library_path = os.environ.get('LD_LIBRARY_PATH')
+    library_paths = library_path.split(':') if library_path else []
+  library_paths.append(
+    os.path.join(os.path.dirname(__file__), 'libyamlstar'))
+  if sys.platform != 'win32':
+    library_paths.append('/usr/local/lib')
+  home = os.environ.get('HOME') or os.path.expanduser('~')
+  if home:
+    library_paths.append(os.path.join(home, '.local', 'lib'))
+
+  # Also check relative to this file (for development)
+  lib_path = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
+    '..', 'libyamlstar', 'lib')
+  library_paths.insert(0, os.path.abspath(lib_path))
+
+  if os.environ.get('YAMLSTAR_GLOJURE'):
+    lib_name, backend = 'libyamlstarglj', 'gloat'
+  else:
+    lib_name, backend = 'libyamlstar', 'graalvm'
+
+  filename = "%s.%s" % (lib_name, so)
+  for path in library_paths:
+    full_path = os.path.join(path, filename)
+    if os.path.isfile(full_path):
+      return full_path, backend
+
+  raise Exception(
+    """\
+Shared library file '%s' not found
+Search paths: %s
+Build with: cd libyamlstar && make build
+""" % (filename, os.pathsep.join(library_paths)))
+
+# Load libyamlstar shared library and detect backend:
+_libyamlstar_path, _backend = find_libyamlstar()
+libyamlstar = ctypes.CDLL(_libyamlstar_path)
+
+# Create bindings to library functions (signatures differ by backend):
+if _backend == 'gloat':
+  # Gloat: functions take (yaml_bytes, opts_bytes) -> json_bytes
+  yamlstar_load_fn = libyamlstar.yamlstar_load
+  yamlstar_load_fn.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+  yamlstar_load_fn.restype = ctypes.c_char_p
+
+  yamlstar_load_all_fn = libyamlstar.yamlstar_load_all
+  yamlstar_load_all_fn.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+  yamlstar_load_all_fn.restype = ctypes.c_char_p
+
+  yamlstar_version_fn = libyamlstar.yamlstar_version
+  yamlstar_version_fn.argtypes = []
+  yamlstar_version_fn.restype = ctypes.c_char_p
+
+else:
+  # GraalVM: functions take (isolatethread, yaml_bytes) -> json_bytes
+  yamlstar_load_fn = libyamlstar.yamlstar_load
+  yamlstar_load_fn.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+  yamlstar_load_fn.restype = ctypes.c_char_p
+
+  yamlstar_load_all_fn = libyamlstar.yamlstar_load_all
+  yamlstar_load_all_fn.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+  yamlstar_load_all_fn.restype = ctypes.c_char_p
+
+  yamlstar_version_fn = libyamlstar.yamlstar_version
+  yamlstar_version_fn.argtypes = [ctypes.c_void_p]
+  yamlstar_version_fn.restype = ctypes.c_char_p
+
+
+# The YAMLStar class is the main user facing API for this module.
+class YAMLStar():
+  """
+  Interface with the libyamlstar shared library.
+
+  Usage:
+    import yamlstar
+    ys = yamlstar.YAMLStar()
+    data = ys.load("key: value")
+    # Returns: {'key': 'value'}
+
+    docs = ys.load_all("---\\ndoc1\\n---\\ndoc2")
+    # Returns: ['doc1', 'doc2']
+  """
+
+  def __init__(self):
+    if _backend == 'graalvm':
+      # Create a new GraalVM isolate thread for the life of this instance:
+      self._isolatethread = ctypes.c_void_p()
+      rc = libyamlstar.graal_create_isolate(
+        None,
+        None,
+        ctypes.byref(self._isolatethread),
+      )
+      if rc != 0:
+        raise Exception("Failed to create GraalVM isolate")
+
+  # Load a single YAML document and return the result:
+  def load(self, yaml_input):
+    """
+    Load a single YAML document.
+
+    Args:
+      yaml_input: String containing YAML content
+
+    Returns:
+      Python object representing the YAML document
+
+    Raises:
+      Exception if the YAML is malformed
+    """
+    self.error = None
+    yaml_bytes = ctypes.c_char_p(bytes(yaml_input, "utf8"))
+
+    if _backend == 'gloat':
+      data_json = yamlstar_load_fn(yaml_bytes, ctypes.c_char_p(b"{}")).decode()
+    else:
+      data_json = yamlstar_load_fn(self._isolatethread, yaml_bytes).decode()
+
+    resp = json.loads(data_json)
+    self.error = resp.get('error')
+    if self.error:
+      raise Exception(self.error['cause'])
+    if 'data' not in resp:
+      raise Exception("Unexpected response from 'libyamlstar'")
+    return resp.get('data')
+
+  # Load all YAML documents and return the results:
+  def load_all(self, yaml_input):
+    """
+    Load all YAML documents from a multi-document string.
+
+    Args:
+      yaml_input: String containing one or more YAML documents
+
+    Returns:
+      List of Python objects, one per YAML document
+
+    Raises:
+      Exception if the YAML is malformed
+    """
+    self.error = None
+    yaml_bytes = ctypes.c_char_p(bytes(yaml_input, "utf8"))
+
+    if _backend == 'gloat':
+      data_json = \
+        yamlstar_load_all_fn(yaml_bytes, ctypes.c_char_p(b"{}")).decode()
+    else:
+      data_json = \
+        yamlstar_load_all_fn(self._isolatethread, yaml_bytes).decode()
+
+    resp = json.loads(data_json)
+    self.error = resp.get('error')
+    if self.error:
+      raise Exception(self.error['cause'])
+    if 'data' not in resp:
+      raise Exception("Unexpected response from 'libyamlstar'")
+    return resp.get('data')
+
+  # Get the YAMLStar version:
+  def version(self):
+    """
+    Get the YAMLStar version string.
+
+    Returns:
+      Version string
+    """
+    if _backend == 'gloat':
+      return yamlstar_version_fn().decode()
+    else:
+      return yamlstar_version_fn(self._isolatethread).decode()
+
+  def __del__(self):
+    if _backend == 'graalvm' and hasattr(self, '_isolatethread'):
+      rc = libyamlstar.graal_tear_down_isolate(self._isolatethread)
+      if rc != 0:
+        raise Exception("Failed to tear down GraalVM isolate")

yamlstar-0.1.7.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: yamlstar
+Version: 0.1.7
+Summary: Python bindings for YAMLStar - YAML 1.2 loader
+Home-page: https://github.com/yaml/yamlstar
+Author: Ingy döt Net
+Author-email: ingy@ingy.net
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.6, <4
+Description-Content-Type: text/markdown
+License-File: License
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# YAMLStar Python Bindings
+
+Python bindings for YAMLStar - a pure YAML 1.2 loader implemented in Clojure.
+
+## Features
+
+- **YAML 1.2 Spec Compliance**: 100% compliant with YAML 1.2 core schema
+- **Pure Implementation**: No dependencies on SnakeYAML or other external parsers
+- **Fast Native Performance**: Uses GraalVM native-image shared library
+- **Simple API**: Load YAML documents with a single function call
+- **Multi-Document Support**: Load multiple YAML documents from a single string
+
+## Installation
+
+### Prerequisites
+
+First, build and install the shared library:
+
+```bash
+cd ../libyamlstar
+make native
+sudo make install PREFIX=/usr/local
+```
+
+Or install to user-local directory:
+
+```bash
+cd ../libyamlstar
+make native
+make install PREFIX=~/.local
+```
+
+### Install Python Package
+
+```bash
+pip install .
+```
+
+For development:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import yamlstar
+
+# Create a YAMLStar instance
+ys = yamlstar.YAMLStar()
+
+# Load a simple YAML string
+data = ys.load("key: value")
+print(data)  # {'key': 'value'}
+```
+
+## Usage Examples
+
+### Basic Types
+
+```python
+import yamlstar
+
+ys = yamlstar.YAMLStar()
+
+# Strings
+ys.load("hello")  # 'hello'
+
+# Integers
+ys.load("42")  # 42
+
+# Floats
+ys.load("3.14")  # 3.14
+
+# Booleans
+ys.load("true")   # True
+ys.load("false")  # False
+
+# Null
+ys.load("null")  # None
+```
+
+### Collections
+
+```python
+# Mappings (dictionaries)
+data = ys.load("""
+name: Alice
+age: 30
+city: Seattle
+""")
+# {'name': 'Alice', 'age': 30, 'city': 'Seattle'}
+
+# Sequences (lists)
+data = ys.load("""
+- apple
+- banana
+- orange
+""")
+# ['apple', 'banana', 'orange']
+
+# Flow style
+data = ys.load("[a, b, c]")
+# ['a', 'b', 'c']
+```
+
+### Nested Structures
+
+```python
+data = ys.load("""
+person:
+  name: Alice
+  age: 30
+  hobbies:
+    - reading
+    - coding
+    - hiking
+""")
+# {
+#   'person': {
+#     'name': 'Alice',
+#     'age': 30,
+#     'hobbies': ['reading', 'coding', 'hiking']
+#   }
+# }
+```
+
+### Multi-Document YAML
+
+```python
+# Load all documents from a multi-document YAML string
+docs = ys.load_all("""---
+name: Document 1
+---
+name: Document 2
+---
+name: Document 3
+""")
+# [
+#   {'name': 'Document 1'},
+#   {'name': 'Document 2'},
+#   {'name': 'Document 3'}
+# ]
+```
+
+### Type Coercion
+
+YAMLStar follows YAML 1.2 core schema type inference:
+
+```python
+data = ys.load("""
+string: hello
+integer: 42
+float: 3.14
+bool_true: true
+bool_false: false
+null_value: null
+""")
+# {
+#   'string': 'hello',
+#   'integer': 42,
+#   'float': 3.14,
+#   'bool_true': True,
+#   'bool_false': False,
+#   'null_value': None
+# }
+```
+
+### Error Handling
+
+```python
+try:
+    data = ys.load("invalid: yaml: syntax")
+except Exception as e:
+    print(f"Error loading YAML: {e}")
+```
+
+### Version Information
+
+```python
+# Get YAMLStar version
+version = ys.version()
+print(f"YAMLStar version: {version}")
+```
+
+## API Reference
+
+### `YAMLStar` Class
+
+#### `__init__()`
+Create a new YAMLStar instance. Each instance maintains its own GraalVM isolate.
+
+```python
+ys = yamlstar.YAMLStar()
+```
+
+#### `load(yaml_input)`
+Load a single YAML document.
+
+**Parameters:**
+- `yaml_input` (str): String containing YAML content
+
+**Returns:**
+- Python object representing the YAML document (dict, list, str, int, float, bool, or None)
+
+**Raises:**
+- `Exception` if the YAML is malformed
+
+**Example:**
+```python
+data = ys.load("key: value")
+```
+
+#### `load_all(yaml_input)`
+Load all YAML documents from a multi-document string.
+
+**Parameters:**
+- `yaml_input` (str): String containing one or more YAML documents
+
+**Returns:**
+- List of Python objects, one per YAML document
+
+**Raises:**
+- `Exception` if the YAML is malformed
+
+**Example:**
+```python
+docs = ys.load_all("---\ndoc1\n---\ndoc2")
+```
+
+#### `version()`
+Get the YAMLStar version string.
+
+**Returns:**
+- str: Version string
+
+**Example:**
+```python
+version = ys.version()
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run only pytest tests
+make test-pytest
+
+# Run only FFI tests
+make test-ffi
+```
+
+### Building Distribution
+
+```bash
+# Build source distribution
+make dist
+
+# Build and install in development mode
+make install
+```
+
+## Requirements
+
+- **Python**: 3.6 or higher
+- **libyamlstar**: Shared library (installed separately)
+- **System**: Linux or macOS
+
+## Library Search Path
+
+The package searches for `libyamlstar.so` (or `.dylib` on macOS) in:
+
+1. Development path (relative to package)
+2. Directories in `LD_LIBRARY_PATH` environment variable
+3. `/usr/local/lib` (default install location)
+4. `~/.local/lib` (user-local install location)
+
+## Comparison to PyYAML
+
+| Feature | YAMLStar | PyYAML |
+|---------|----------|--------|
+| YAML Version | 1.2 | 1.1 |
+| Implementation | Pure Clojure | C + Python |
+| Type Inference | YAML 1.2 core schema | YAML 1.1 + custom |
+| Native Performance | Yes (GraalVM) | Yes (C extension) |
+| Dependencies | libyamlstar.so | None |
+
+## License
+
+MIT License - See [License](License) file
+
+## Credits
+
+Created by Ingy döt Net, inventor of YAML.
+
+YAMLStar is built on the YAML Reference Parser (pure Clojure implementation).
+
+## Links
+
+- **GitHub**: https://github.com/yaml/yamlstar
+- **YAML Specification**: https://yaml.org/spec/1.2/spec.html

yamlstar-0.1.7.dist-info/RECORD

@@ -0,0 +1,7 @@
+yamlstar/__init__.py,sha256=EPM3z5ags82yy6tVHVvD13JOh1Z0fPj2WVVXL8LicXI,6779
+yamlstar/libyamlstar/libyamlstar.dll,sha256=fYId0oOi06QgfJaIM3F4_g4unA2hMZTXNsyYicsqv1Y,28422144
+yamlstar-0.1.7.dist-info/licenses/License,sha256=nsvXzFX7z_XslsE0ha08FgKK6e3GjjJYDNFjTZOCQs4,1091
+yamlstar-0.1.7.dist-info/METADATA,sha256=4fIDiQIOPXTcefixRHspDxjEPFEO9KXl3sPhsDIS4rM,6639
+yamlstar-0.1.7.dist-info/WHEEL,sha256=QR8DNjG6Lr6bNErJWJgF4dP2dJ2N7NpY-BWly1OvcTM,97
+yamlstar-0.1.7.dist-info/top_level.txt,sha256=cior1pgLvANIQ6HE_xAofUnhWLpPGeZtkp8_1JY_JRc,9
+yamlstar-0.1.7.dist-info/RECORD,,

yamlstar-0.1.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

yamlstar-0.1.7.dist-info/licenses/License

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 yaml.com
+
+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.

yamlstar-0.1.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+yamlstar