cooklang-py 0.1.0__tar.gz

cooklang_py-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dan Shernicoff
+
+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.

cooklang_py-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: cooklang-py
+Version: 0.1.0
+Summary: Python Parser for Cooklang
+Author: Dan Shernicoff
+Author-email: Dan Shernicoff <dan@brassnet.biz>
+License-Expression: MIT
+License-File: LICENSE.md
+Requires-Dist: frontmatter>=3.0.8
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/brass75/cooklang-py
+Project-URL: cooklang, https://cooklang.org
+Project-URL: homepage, https://github.com/brass75/cooklang-py
+Description-Content-Type: text/markdown
+
+# cooklang-py
+
+A parser for the [Cooklang recipe markup language](https://cooklang.org)
+
+## Installation
+
+To install just run:
+
+```shell
+pip install cooklang-py
+```
+
+## `Recipe`
+
+The `Recipe` is the primary unit. There are 2 ways to create a `Recipe` object:
+
+```python
+from cooklang_py import Recipe
+
+# Create from a string in memory
+recipe_string = '<your recipe here>'
+recipe = Recipe(recipe_string)
+
+# Create from a file
+recipe_file = '/path/to/recipe/file'
+recipe = Recipe.from_file(recipe_file)
+```
+
+Just like a recipe in a book a `Recipe` contains:
+
+- Ingredients
+- Cookware / equipment
+- Timings
+- Metadata (servings, cook time, etc.)
+
+To see how to define these in your input please refer to the
+[Cooklang language specification](https://cooklang.org/docs/spec/#comments)
+
+When the recipe is parsed there will be a list of `Step` objects. Each step object can contain:
+
+- Ingredients
+- Cookware
+- Timings
+- Instructions (text)
+
+At both the `Recipe` and `Step` level you can access the list of `Ingredients` and `Cookware`
+for the recipe or step.
+
+### Cookware, Timings, and Ingredients
+
+Cookware, timings, and ingredients are the backbone of the recipe. In this package all three
+inherit from the `BaseObj`. They all have the following 3 attributes:
+
+- `name` - the name of the item (i.e. pot, carrot, etc.)
+- `quantity` - how much is needed
+  - For `Ingredient` quantity defaults to "some" if it is not set.
+  - For `Cookware` quantity defaults to 1 if it is not set.
+- `notes` - any notes for the item (i.e. "greased", "peeled and diced", etc.)
+  - `Timings` do not have notes per the Cooklang specification.
+
+## Compatibility
+
+`cooklang-py` passes all canonical tests defined at
+[https://github.com/cooklang/cooklang-rs/blob/main/tests/canonical.yaml](https://github.com/cooklang/cooklang-rs/blob/main/tests/canonical.yaml)
+for the following platforms:
+
+- Linux
+- MacOS
+- Windows (with the exception of test cases with Unicode characters.)

cooklang_py-0.1.0/README.md

@@ -0,0 +1,69 @@
+# cooklang-py
+
+A parser for the [Cooklang recipe markup language](https://cooklang.org)
+
+## Installation
+
+To install just run:
+
+```shell
+pip install cooklang-py
+```
+
+## `Recipe`
+
+The `Recipe` is the primary unit. There are 2 ways to create a `Recipe` object:
+
+```python
+from cooklang_py import Recipe
+
+# Create from a string in memory
+recipe_string = '<your recipe here>'
+recipe = Recipe(recipe_string)
+
+# Create from a file
+recipe_file = '/path/to/recipe/file'
+recipe = Recipe.from_file(recipe_file)
+```
+
+Just like a recipe in a book a `Recipe` contains:
+
+- Ingredients
+- Cookware / equipment
+- Timings
+- Metadata (servings, cook time, etc.)
+
+To see how to define these in your input please refer to the
+[Cooklang language specification](https://cooklang.org/docs/spec/#comments)
+
+When the recipe is parsed there will be a list of `Step` objects. Each step object can contain:
+
+- Ingredients
+- Cookware
+- Timings
+- Instructions (text)
+
+At both the `Recipe` and `Step` level you can access the list of `Ingredients` and `Cookware`
+for the recipe or step.
+
+### Cookware, Timings, and Ingredients
+
+Cookware, timings, and ingredients are the backbone of the recipe. In this package all three
+inherit from the `BaseObj`. They all have the following 3 attributes:
+
+- `name` - the name of the item (i.e. pot, carrot, etc.)
+- `quantity` - how much is needed
+  - For `Ingredient` quantity defaults to "some" if it is not set.
+  - For `Cookware` quantity defaults to 1 if it is not set.
+- `notes` - any notes for the item (i.e. "greased", "peeled and diced", etc.)
+  - `Timings` do not have notes per the Cooklang specification.
+
+## Compatibility
+
+`cooklang-py` passes all canonical tests defined at
+[https://github.com/cooklang/cooklang-rs/blob/main/tests/canonical.yaml](https://github.com/cooklang/cooklang-rs/blob/main/tests/canonical.yaml)
+for the following platforms:
+
+- Linux
+- MacOS
+- Windows (with the exception of test cases with Unicode characters.)

cooklang_py-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "cooklang_py"
+version = "0.1.0"
+description = "Python Parser for Cooklang"
+readme = "README.md"
+authors = [{name = "Dan Shernicoff", email = "dan@brassnet.biz"}]
+license = "MIT"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.10"
+dependencies = [
+    "frontmatter>=3.0.8",
+]
+
+[dependency-groups]
+dev = [
+    "coverage>=7.9.1",
+    "pre-commit>=4.2.0",
+    "pytest>=8.4.1",
+    "pytest-cov>=6.2.1",
+    "ruff>=0.12.1",
+    "uv-build>=0.7.12,<0.8.0",
+]
+
+[project.urls]
+homepage = "https://github.com/brass75/cooklang-py"
+Repository = "https://github.com/brass75/cooklang-py"
+cooklang = "https://cooklang.org"
+
+[tool.ruff]
+target-version = "py312"
+# Allow lines to be as long as 120 characters.
+line-length = 120
+lint.select = [
+  "E",   # pycodestyle
+  "F",   # pyflakes
+  "UP",  # pyupgrade
+  "I",   # imports
+]
+
+
+lint.ignore = [
+]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+lint.fixable = ["ALL"]
+lint.unfixable = []
+
+exclude = [
+]
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+docstring-code-format = true
+
+[build-system]
+requires = ["uv_build>=0.7.12,<0.8.0"]
+build-backend = "uv_build"

cooklang_py-0.1.0/src/cooklang_py/__init__.py

@@ -0,0 +1,4 @@
+from .base_objects import Cookware, Ingredient, Quantity, Timing
+from .recipe import Metadata, Recipe, Step
+
+__all__ = ['Recipe', 'Step', 'Ingredient', 'Cookware', 'Timing', 'Quantity', 'Metadata']

cooklang_py-0.1.0/src/cooklang_py/base_objects.py

@@ -0,0 +1,174 @@
+"""Base Object for Ingredient, Cookware, and Timing"""
+
+import re
+from decimal import Decimal, InvalidOperation
+from fractions import Fraction
+
+from .const import NOTE_PATTERN, QUANTITY_PATTERN, UNIT_MAPPINGS
+
+
+class Quantity:
+    """Quantity Class"""
+
+    def __init__(self, qstr: str):
+        self._raw = qstr
+        self.unit = ''
+        if '%' in qstr:
+            self.amount, self.unit = qstr.split('%')
+            self.unit = self.unit.strip()
+        else:
+            self.amount = qstr
+        self.amount = self.amount.strip()
+
+        # Try storing the quantity as a numeric value
+        try:
+            if '/' in self.amount:
+                self.amount = Fraction(re.sub(r'\s+', '', self.amount))
+            elif '.' in self.amount:
+                self.amount = Decimal(self.amount)
+            else:
+                self.amount = int(self.amount)
+        except (ValueError, InvalidOperation):
+            pass
+
+    def __eq__(self, other):
+        if not isinstance(other, Quantity):
+            return False
+        return self.amount == other.amount and self.unit == other.unit
+
+    def __str__(self):
+        return f'{self.amount} {UNIT_MAPPINGS.get(self.unit, self.unit)}'.strip()
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}(qstr={repr(self._raw)})'
+
+
+class BaseObj:
+    """Base Object for Ingredient, Cookware, and Timing"""
+
+    prefix = None
+    supports_notes = True
+
+    def __init__(
+        self,
+        raw: str,
+        name: str,
+        *,
+        quantity: str = None,
+        notes: str = None,
+    ):
+        """
+        Constructor for the BaseObj class
+
+        :param raw: The raw string the ingredient came from
+        :param name: The name of the ingredient
+        :param quantity: The quantity as described in the raw string
+        :param notes: Notes from the raw string
+        """
+        self.raw = raw
+        self.name = name.strip()
+        self._quantity = quantity.strip() if quantity else None
+        self.notes = notes
+        self._parsed_quantity = Quantity(quantity) if quantity else ''
+
+    def __eq__(self, other):
+        if not (isinstance(other, BaseObj)):
+            return False
+        return all(getattr(self, attr) == getattr(other, attr) for attr in ('name', '_parsed_quantity', 'notes'))
+
+    @property
+    def long_str(self) -> str:
+        """Formatted string"""
+        s = str(self.quantity) + ' ' if self.quantity else ''
+        s = f'{s}{self.name}'
+        if self.notes:
+            s += f' ({self.notes})'
+        return s.strip()
+
+    def __repr__(self):
+        s = f'{self.__class__.__name__}(raw={self.raw!r}, name={self.name!r}, quantity={self._quantity!r}'
+        if self.__class__.supports_notes:
+            s += f', notes={repr(self.notes)}'
+        return s + ')'
+
+    @property
+    def quantity(self) -> str:
+        return self._parsed_quantity
+
+    def __str__(self):
+        """Short version of the formatted string"""
+        if self.quantity:
+            return f'{self.name} ({self.quantity})'.strip()
+        return self.name
+
+    def __hash__(self):
+        return hash(self.raw)
+
+    @classmethod
+    def factory(cls, raw: str):
+        """
+        Factory to create an object
+
+        :param raw: raw string to create from
+        :return: An object of cls
+        """
+        if not cls.prefix:
+            raise NotImplementedError(f'{cls.__name__} does not have a prefix set!')
+        if not raw.startswith(cls.prefix):
+            raise ValueError(f'Raw string does not start with {repr(cls.prefix)}: [{repr(raw[0])}]')
+        raw = raw[1:]
+        if next_object_starts := [raw.index(prefix) for prefix in PREFIXES if prefix in raw]:
+            next_start = min(next_object_starts)
+            raw = raw[:next_start]
+        note_pattern = NOTE_PATTERN if cls.supports_notes else ''
+        if match := re.search(rf'(?P<name>.*?){QUANTITY_PATTERN}{note_pattern}', raw):
+            return cls(f'{cls.prefix}{raw[: match.end(match.lastgroup) + 1]}', **match.groupdict())
+        if note_pattern and (match := re.search(rf'^(P<name>[\S]+){note_pattern}', raw)):
+            return cls(f'{cls.prefix}{raw[: match.end(match.lastgroup) + 1]}', **match.groupdict())
+        name = raw.split()[0]
+        name = re.sub(r'\W+$', '', name) or name
+        return cls(f'{cls.prefix}{name}', name=name)
+
+
+class Ingredient(BaseObj):
+    """Ingredient"""
+
+    prefix = '@'
+    supports_notes = True
+
+    def __init__(self, *args, **kwargs):
+        if not kwargs.get('quantity', '').strip():
+            kwargs['quantity'] = 'some'
+        super().__init__(*args, **kwargs)
+
+
+class Cookware(BaseObj):
+    """Ingredient"""
+
+    prefix = '#'
+    supports_notes = True
+
+    def __init__(self, *args, **kwargs):
+        if not kwargs.get('quantity', '').strip():
+            kwargs['quantity'] = '1'
+        super().__init__(*args, **kwargs)
+
+
+class Timing(BaseObj):
+    """Ingredient"""
+
+    prefix = '~'
+    supports_notes = False
+
+    def __str__(self):
+        return str(self.quantity).strip()
+
+    def long_str(self) -> str:
+        return str(self)
+
+
+PREFIXES = {
+    '@': Ingredient,
+    '#': Cookware,
+    '~': Timing,
+}

cooklang_py-0.1.0/src/cooklang_py/const.py

@@ -0,0 +1,42 @@
+"""Constants"""
+
+QUANTITY_PATTERN = r'(?<!\\){(?P<quantity>.*?)}'
+NOTE_PATTERN = r'(?:\((?P<notes>.*)\))?'
+
+UNIT_MAPPINGS = {
+    'teaspoon': 'tsp',
+    'tablespoon': 'tbsp',
+    'quart': 'qt',
+    'gallon': 'gal',
+    'kilo': 'kg',
+    'gram': 'g',
+    'ounce': 'oz',
+    'pound': 'lb',
+    'liter': 'l',
+    'milliliter': 'ml',
+}
+
+METADATA_MAPPINGS = {
+    'source': 'source.name',
+    'author': 'source.author',
+    'serves': 'servings',
+    'yield': 'servings',
+    'course': 'category',
+    'time required': 'duration',
+    'time': 'duration',
+    'prep time': 'time.prep',
+    'cook time': 'time.cook',
+    'image': 'images',
+    'picture': 'images',
+    'pictures': 'images',
+    'introduction': 'description',
+}
+
+METADATA_DISPLAY_MAP = {
+    'source.name': 'Recipe from',
+    'source.author': 'Recipe author',
+    'source.url': 'Recipe URL',
+    'duration': 'Total cook time',
+    'time.prep': 'Prep time',
+    'time.cook': 'Cook time',
+}

cooklang_py-0.1.0/src/cooklang_py/recipe.py

@@ -0,0 +1,138 @@
+import re
+from os import PathLike
+
+import frontmatter
+
+from .base_objects import PREFIXES, Cookware, Ingredient
+from .const import METADATA_DISPLAY_MAP, METADATA_MAPPINGS
+
+
+class Metadata:
+    """Recipe Metadata Class"""
+
+    def __init__(self, metadata: str):
+        self._parsed = frontmatter.Frontmatter().read(metadata)
+        attributes = self._parsed.get('attributes')
+        if isinstance(attributes, str):
+            attrs = dict()
+            for line in attributes.splitlines():
+                if ':' not in line:
+                    continue
+                key, value = line.split(':', 1)
+                attrs[key.strip()] = value
+            attributes = attrs
+        self._parsed = {k.strip(): v for k, v in attributes.items()}
+        self._mapped = {METADATA_MAPPINGS.get(k.lower(), k.lower()): v for k, v in self._parsed.items()}
+        for attr, value in self._mapped.items():
+            setattr(self, attr, value)
+
+        for attr, value in self._parsed.items():
+            setattr(self, attr, value)
+
+    def __str__(self):
+        s = ''
+        for k, v in self._mapped.items():
+            s += f'{METADATA_DISPLAY_MAP.get(k, k).capitalize()}: {v}\n'
+        if s:
+            return s + ('-' * 50) + '\n'
+        return s
+
+
+class Recipe:
+    def __init__(self, recipe: str):
+        self._raw = recipe
+        if match := re.search(r'(---.*---\s*)(.*)', recipe, re.DOTALL):
+            self.metadata = Metadata(match.group(1))
+            body = match.group(2)
+        else:
+            body = recipe
+        if not body:
+            raise ValueError('No body found in recipe!')
+        self.steps = list()
+        self.ingredients = list()
+        self.cookware = list()
+        for line in re.split(r'\n{2,}', body):
+            line = re.sub(r'\s+', ' ', line)
+            if step := Step(line):
+                self.steps.append(step)
+                self.ingredients.extend(step.ingredients)
+                self.cookware.extend(step.cookware)
+
+    def __iter__(self):
+        yield from self.steps
+
+    def __len__(self):
+        return len(self.steps)
+
+    def __str__(self):
+        s = str(self.metadata)
+        s += 'Ingredients:\n\n'
+        s += '\n'.join(ing.long_str for ing in self.ingredients)
+        s += '\n' + ('-' * 50) + '\n'
+        if self.cookware:
+            s += '\nCookware:\n\n'
+            s += '\n'.join(ing.long_str for ing in self.cookware)
+            s += '\n' + ('-' * 50) + '\n'
+        s += '\n'
+        s += '\n'.join(map(str, self))
+        return s.replace('\\', '') + '\n'
+
+    @staticmethod
+    def from_file(filename: PathLike):
+        """
+        Load a recipe from a file
+
+        :param filename: Path like object indicating the location of the file.
+        :return: Recipe object
+        """
+        with open(filename) as f:
+            return Recipe(f.read())
+
+
+class Step:
+    def __init__(self, line: str):
+        self._raw = line
+        self.ingredients = list()
+        self.cookware = list()
+        self._sections = list()
+        self.parse(line)
+
+    def __iter__(self):
+        yield from self._sections
+
+    def __len__(self):
+        return len(self._sections)
+
+    def __repr__(self):
+        return repr(self._sections)
+
+    def parse(self, line: str):
+        """
+        Parse a line into its component parts
+        :param line:
+        :return:
+        """
+        if not (section := self._remove_comments(line)):
+            return
+        self._sections.clear()
+        while match := re.search(r'(?<!\\)[@#~][\S]', section):
+            if section[: match.start()].strip():
+                self._sections.append(section[: match.start()])
+            section = section[match.start() :]
+            obj = PREFIXES[section[0]].factory(section)
+            self._sections.append(obj)
+            section = section.removeprefix(obj.raw)
+            match obj:
+                case Ingredient():
+                    self.ingredients.append(obj)
+                case Cookware():
+                    self.cookware.append(obj)
+        if section.strip():
+            self._sections.append(section)
+
+    def __str__(self):
+        return ''.join(map(str, self)).rstrip()
+
+    @staticmethod
+    def _remove_comments(line: str) -> str:
+        return re.sub(r'--.*(?:$|\n)|\[-.*?-]', '', line)