half-orm 0.18.12__tar.gz → 1.0.0__tar.gz

{half_orm-0.18.12 → half_orm-1.0.0}/AUTHORS

@@ -1,2 +1,3 @@
 # This is the list of half_orm's significant contributors.
 # Hopefully, it will become larger...
+Joël Maizi

half_orm-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: half_orm
+Version: 1.0.0
+Summary: A database-first ORM for PostgreSQL
+Author-email: Joël Maïzi <joel.maizi@collorg.org>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/half-orm/half-orm
+Project-URL: Documentation, https://half-orm.github.io/half-orm/
+Project-URL: Changelog, https://github.com/half-orm/half-orm/blob/main/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: psycopg[binary]
+Requires-Dist: click
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# halfORM
+
+[![PyPI version](https://img.shields.io/pypi/v/half_orm)](https://pypi.org/project/half-orm/)
+[![Python versions](https://img.shields.io/badge/Python-%20≥%203.9-blue)](https://www.python.org)
+[![PostgreSQL versions](https://img.shields.io/badge/PostgreSQL-%20≥%209.6-blue)](https://www.postgresql.org)
+[![License](https://img.shields.io/pypi/l/half_orm?color=green)](https://pypi.org/project/half-orm/)
+[![Tests](https://github.com/half-orm/half-orm/actions/workflows/python-package.yml/badge.svg)](https://github.com/half-orm/half-orm/actions/workflows/python-package.yml)
+[![Coverage](https://coveralls.io/repos/github/half-orm/half-orm/badge.svg?branch=main)](https://coveralls.io/github/half-orm/half-orm?branch=main)
+[![Downloads](https://static.pepy.tech/badge/half_orm)](https://pepy.tech/project/half_orm)
+
+> ## ⚠️ BREAKING CHANGES in v1.0.0
+>
+> **Legacy unprefixed API removed** — the pre-`ho_` method names, deprecated
+> since 0.x, no longer exist: `select`, `insert`, `update`, `delete`, `get`,
+> `count`, `is_empty`, `unaccent`, `order_by`, `limit`, `offset`, `_mogrify`.
+> Use their `ho_`-prefixed equivalents (`ho_select`, `ho_insert`, `ho_update`,
+> `ho_delete`, `ho_get`, `ho_count`, `ho_is_empty`, `ho_unaccent`, `ho_mogrify`,
+> passing `order_by`/`limit`/`offset` as `ho_select()` keyword arguments).
+>
+> **`DC_Relation`** removed from `half_orm.relation` — this IDE type-checking
+> stub is now generated per-project by `half-orm-dev` instead of shipped in
+> the library.
+>
+> **`ho_get()`** is now public and returns a `dict` directly. It raises
+> `NotFoundError` (0 rows) or `MultipleRowsError` (> 1 row) instead of
+> counting first.
+>
+> **Deprecated query-builder setters removed** — `ho_limit`, `ho_offset`,
+> `ho_order_by`, `ho_distinct` no longer exist as setters. Pass these as
+> keyword arguments to `ho_select()`:
+> ```python
+> # Before (0.x)
+> rel.ho_limit = 10
+> rel.ho_order_by = 'name'
+> list(rel)
+>
+> # After (1.0)
+> list(rel.ho_select(limit=10, order_by='name'))
+> ```
+>
+> **`FKEYS_PROPERTIES` / `FKEYS`** class attributes removed — use `Fkeys` only.
+>
+> **`ho_cast()`** now raises `CastError` if the target is not in the
+> PostgreSQL inheritance hierarchy of the relation.
+>
+> See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+halfORM is a database-first ORM for PostgreSQL. Your schema lives in the
+database; halfORM introspects it at runtime and gives you Python objects to work
+with your data. No migrations, no code generation.
+
+**The central idea:** a `Relation` object is a **predicate**. It describes the
+logical condition that rows must satisfy to belong to the relation. Its
+*extension* — the set of rows currently satisfying the predicate in the
+database — is what you read, update, or delete.
+
+## Key features
+
+- **Database-first** — the schema lives in PostgreSQL, not in Python classes.
+- **Predicate model** — relations are predicates; set operators (`|`, `&`, `-`)
+  compose them before any SQL is sent.
+- **FK navigation** — join across tables (and views) by setting FK attributes;
+  explicit `Fkeys` dict for views where PostgreSQL stores no FK metadata.
+- **Sync + async** — every executor has an `a`-prefixed async counterpart
+  (`ho_aselect`, `ho_ainsert`, …).
+- **Bulk load** — `ho_copy` / `ho_acopy` for high-throughput inserts via
+  PostgreSQL `COPY`.
+- **No magic** — queries are built from the predicate you describe and executed
+  only when you call an executor. `ho_mogrify()` shows the exact SQL.
+
+## Install
+
+```bash
+pip install half_orm
+```
+
+Requires **[psycopg 3](https://www.psycopg.org/psycopg3/)** (`psycopg[binary]`).
+
+## Configure
+
+```ini
+# ~/.half_orm/blog
+[database]
+name     = blog
+user     = alice
+password = secret
+host     = localhost
+```
+
+## Usage
+
+```python
+from half_orm.model import Model
+from half_orm.relation_errors import NotFoundError, MultipleRowsError
+
+blog   = Model('blog')
+Post   = blog.get_relation_class('blog.post')
+Author = blog.get_relation_class('blog.author')
+
+# Insert — returns the inserted row as a dict
+alice = Author(
+    first_name='Alice', last_name='Martin', email='alice@example.com'
+).ho_insert()
+
+# Query — Author(last_name='Martin') is a predicate, not a query
+for row in Author(last_name='Martin').ho_select('id', 'email'):
+    print(row)
+
+# Get exactly one row
+try:
+    author = Author(last_name='Martin').ho_get()
+except NotFoundError:
+    print("no such author")
+except MultipleRowsError:
+    print("ambiguous — more than one author named Martin")
+
+# FK navigation — no JOIN written by hand
+post = Post(id=1)
+post.author_fk.set()                         # join all authors
+for row in post.ho_select(json_agg={'author_fk': ['first_name', 'last_name']}):
+    print(row['author_fk'])                  # {'first_name': 'Alice', 'last_name': 'Martin'}
+
+# Set operators — compose predicates before hitting the database
+recent   = Post(created_at=('>', '2024-01-01'))
+featured = Post(featured=True)
+combined = recent | featured                 # UNION
+print(combined.ho_count())
+
+# Update / delete
+Author(id=alice['id']).ho_update(email='alice@newdomain.com')
+Author(id=alice['id']).ho_delete()
+```
+
+## Documentation
+
+- [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
+- [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
+
+## Extensions
+
+| Extension | Description |
+|-----------|-------------|
+| [half-orm-dev](https://github.com/half-orm/half-orm-dev) | Development tools — `half_orm dev` project scaffolding, patch management, and schema synchronisation. |
+
+## License
+
+halfORM is licensed under the [GPL-3.0](LICENSE) license.

half_orm-1.0.0/README.md

@@ -0,0 +1,147 @@
+# halfORM
+
+[![PyPI version](https://img.shields.io/pypi/v/half_orm)](https://pypi.org/project/half-orm/)
+[![Python versions](https://img.shields.io/badge/Python-%20≥%203.9-blue)](https://www.python.org)
+[![PostgreSQL versions](https://img.shields.io/badge/PostgreSQL-%20≥%209.6-blue)](https://www.postgresql.org)
+[![License](https://img.shields.io/pypi/l/half_orm?color=green)](https://pypi.org/project/half-orm/)
+[![Tests](https://github.com/half-orm/half-orm/actions/workflows/python-package.yml/badge.svg)](https://github.com/half-orm/half-orm/actions/workflows/python-package.yml)
+[![Coverage](https://coveralls.io/repos/github/half-orm/half-orm/badge.svg?branch=main)](https://coveralls.io/github/half-orm/half-orm?branch=main)
+[![Downloads](https://static.pepy.tech/badge/half_orm)](https://pepy.tech/project/half_orm)
+
+> ## ⚠️ BREAKING CHANGES in v1.0.0
+>
+> **Legacy unprefixed API removed** — the pre-`ho_` method names, deprecated
+> since 0.x, no longer exist: `select`, `insert`, `update`, `delete`, `get`,
+> `count`, `is_empty`, `unaccent`, `order_by`, `limit`, `offset`, `_mogrify`.
+> Use their `ho_`-prefixed equivalents (`ho_select`, `ho_insert`, `ho_update`,
+> `ho_delete`, `ho_get`, `ho_count`, `ho_is_empty`, `ho_unaccent`, `ho_mogrify`,
+> passing `order_by`/`limit`/`offset` as `ho_select()` keyword arguments).
+>
+> **`DC_Relation`** removed from `half_orm.relation` — this IDE type-checking
+> stub is now generated per-project by `half-orm-dev` instead of shipped in
+> the library.
+>
+> **`ho_get()`** is now public and returns a `dict` directly. It raises
+> `NotFoundError` (0 rows) or `MultipleRowsError` (> 1 row) instead of
+> counting first.
+>
+> **Deprecated query-builder setters removed** — `ho_limit`, `ho_offset`,
+> `ho_order_by`, `ho_distinct` no longer exist as setters. Pass these as
+> keyword arguments to `ho_select()`:
+> ```python
+> # Before (0.x)
+> rel.ho_limit = 10
+> rel.ho_order_by = 'name'
+> list(rel)
+>
+> # After (1.0)
+> list(rel.ho_select(limit=10, order_by='name'))
+> ```
+>
+> **`FKEYS_PROPERTIES` / `FKEYS`** class attributes removed — use `Fkeys` only.
+>
+> **`ho_cast()`** now raises `CastError` if the target is not in the
+> PostgreSQL inheritance hierarchy of the relation.
+>
+> See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+halfORM is a database-first ORM for PostgreSQL. Your schema lives in the
+database; halfORM introspects it at runtime and gives you Python objects to work
+with your data. No migrations, no code generation.
+
+**The central idea:** a `Relation` object is a **predicate**. It describes the
+logical condition that rows must satisfy to belong to the relation. Its
+*extension* — the set of rows currently satisfying the predicate in the
+database — is what you read, update, or delete.
+
+## Key features
+
+- **Database-first** — the schema lives in PostgreSQL, not in Python classes.
+- **Predicate model** — relations are predicates; set operators (`|`, `&`, `-`)
+  compose them before any SQL is sent.
+- **FK navigation** — join across tables (and views) by setting FK attributes;
+  explicit `Fkeys` dict for views where PostgreSQL stores no FK metadata.
+- **Sync + async** — every executor has an `a`-prefixed async counterpart
+  (`ho_aselect`, `ho_ainsert`, …).
+- **Bulk load** — `ho_copy` / `ho_acopy` for high-throughput inserts via
+  PostgreSQL `COPY`.
+- **No magic** — queries are built from the predicate you describe and executed
+  only when you call an executor. `ho_mogrify()` shows the exact SQL.
+
+## Install
+
+```bash
+pip install half_orm
+```
+
+Requires **[psycopg 3](https://www.psycopg.org/psycopg3/)** (`psycopg[binary]`).
+
+## Configure
+
+```ini
+# ~/.half_orm/blog
+[database]
+name     = blog
+user     = alice
+password = secret
+host     = localhost
+```
+
+## Usage
+
+```python
+from half_orm.model import Model
+from half_orm.relation_errors import NotFoundError, MultipleRowsError
+
+blog   = Model('blog')
+Post   = blog.get_relation_class('blog.post')
+Author = blog.get_relation_class('blog.author')
+
+# Insert — returns the inserted row as a dict
+alice = Author(
+    first_name='Alice', last_name='Martin', email='alice@example.com'
+).ho_insert()
+
+# Query — Author(last_name='Martin') is a predicate, not a query
+for row in Author(last_name='Martin').ho_select('id', 'email'):
+    print(row)
+
+# Get exactly one row
+try:
+    author = Author(last_name='Martin').ho_get()
+except NotFoundError:
+    print("no such author")
+except MultipleRowsError:
+    print("ambiguous — more than one author named Martin")
+
+# FK navigation — no JOIN written by hand
+post = Post(id=1)
+post.author_fk.set()                         # join all authors
+for row in post.ho_select(json_agg={'author_fk': ['first_name', 'last_name']}):
+    print(row['author_fk'])                  # {'first_name': 'Alice', 'last_name': 'Martin'}
+
+# Set operators — compose predicates before hitting the database
+recent   = Post(created_at=('>', '2024-01-01'))
+featured = Post(featured=True)
+combined = recent | featured                 # UNION
+print(combined.ho_count())
+
+# Update / delete
+Author(id=alice['id']).ho_update(email='alice@newdomain.com')
+Author(id=alice['id']).ho_delete()
+```
+
+## Documentation
+
+- [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
+- [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
+
+## Extensions
+
+| Extension | Description |
+|-----------|-------------|
+| [half-orm-dev](https://github.com/half-orm/half-orm-dev) | Development tools — `half_orm dev` project scaffolding, patch management, and schema synchronisation. |
+
+## License
+
+halfORM is licensed under the [GPL-3.0](LICENSE) license.

{half_orm-0.18.12 → half_orm-1.0.0}/half_orm/__main__.py

@@ -50,7 +50,7 @@ def check_databases_access():
     except FileNotFoundError:
         sys.stderr.write(f"❌ '{CONF_DIR}' does not exist.\nChange HALFORM_CONF_DIR variable\n")
     sys.stderr.flush()
-    print(f"\nCheck the documentation on https://half-orm.github.io/half-orm/tutorial/installation/#database-configuration-optional")
+    print(f"\nCheck the documentation on https://half-orm.github.io/half-orm/half-an-hour/#1-connect-1-min")
 
 def show_version():
     print(f"[halfORM] version {half_orm.__version__}")

{half_orm-0.18.12 → half_orm-1.0.0}/half_orm/cli.py

@@ -43,6 +43,17 @@ class CustomGroup(click.Group):
 
     def resolve_command(self, ctx, args):
         """Override to show available commands when command not found."""
+        extensions = discover_extensions()
+        for ext_data in extensions.values():
+            pre_check = ext_data.get('pre_check')
+            if pre_check is not None:
+                try:
+                    pre_check(ctx)
+                except (click.ClickException, SystemExit):
+                    raise
+                except Exception as e:
+                    raise click.ClickException(str(e))
+
         try:
             return super().resolve_command(ctx, args)
         except click.UsageError as e:
@@ -87,6 +98,7 @@ OFFICIAL_EXTENSIONS = {
     'half_orm_test_extension',
     'half_orm_inspect',
     'half_orm_dev',
+    'half_orm_gen'
 }
 
 def get_config_file():
@@ -253,7 +265,8 @@ def discover_extensions() -> Dict[str, Any]:
                     'package_name': package_name,
                     'version': current_version,
                     'metadata': pkg_metadata,  # Use auto-discovered metadata
-                    'display_name': display_name
+                    'display_name': display_name,
+                    'pre_check': getattr(extension_module, 'pre_check', None),
                 }
 
         except ImportError as exc:

{half_orm-0.18.12 → half_orm-1.0.0}/half_orm/field.py

@@ -6,12 +6,43 @@
 import re
 import sys
 import typing
+import warnings
+import yaml
 from collections.abc import Iterable
 from half_orm.null import NULL
 from half_orm.sql_adapter import SQL_ADAPTER
 from half_orm.sql_ast import FieldExpr
 
 
+_TEXT_LIKE_TYPES = {'text', 'varchar', 'character varying', 'char', 'bpchar', 'name', 'citext'}
+
+
+def is_text_like_sql_type(sql_type: str) -> bool:
+    """True if `sql_type` (a PostgreSQL type name, e.g. from ho_meta()'s
+    per-field 'sql_type') is one ``ilike``/``unaccent`` make sense against.
+
+    Array types (leading ``_``, e.g. ``_text``) are unwrapped first. Used by
+    :attr:`Field._is_text_like` internally, and by callers outside this
+    module (e.g. half_orm_gen's search) that need the same "is this a text
+    type" judgment before choosing a comparator, without duplicating the
+    type list.
+    """
+    return sql_type.lstrip('_') in _TEXT_LIKE_TYPES
+
+# (comparator, column_sql_type) -> right-hand-side SQL template (with a single
+# '%s' bind placeholder), used instead of the default "cast the bound value to
+# the column's own type" behavior. Needed whenever a PostgreSQL operator's
+# right operand isn't of the same type as the left (column) operand — e.g.
+# `tsvector @@ tsquery`, not `tsvector @@ tsvector` — so a bare `%s::sql_type`
+# cast would be wrong (or, for tsquery specifically, would reject a plain
+# multi-word search string since the tsquery input parser requires explicit
+# &/|/! operators between lexemes; plainto_tsquery() builds a valid tsquery
+# from free text instead).
+_OPERATOR_RHS_TEMPLATES = {
+    ('@@', 'tsvector'): 'plainto_tsquery(%s)',
+}
+
+
 class Expr:
     """A raw SQL expression for use with :meth:`Field.set`.
 
@@ -82,6 +113,7 @@ class Field():
         self.__value = None
         self.__unaccent = False
         self.__comp = '='
+        self.__json_schema = self.__parse_json_schema()
 
     @property
     def _relation(self): # pragma: no cover
@@ -165,13 +197,63 @@ class Field():
         """
         return bool(self.__metadata['notnull'])
 
+    @property
+    def has_default_value(self):
+        """The default expression for this column, or ``None`` if there is none.
+
+        Returns the PostgreSQL expression string as stored in ``pg_attrdef``,
+        e.g. ``"nextval('seq'::regclass)"``, ``"'active'::text"``, ``"now()"``.
+
+        Example::
+
+            Author().id.has_default_value        # "nextval('author_id_seq'::regclass)"
+            Author().last_name.has_default_value # None
+        """
+        return self.__metadata.get('default_expr')
+
+    def __parse_json_schema(self):
+        desc = self.__metadata.get('fielddescription') or ''
+        m = re.search(r'@json\s*```yaml\s*(.*?)(?:```|\Z)', desc, re.DOTALL)
+        if not m:
+            return None
+        try:
+            return yaml.safe_load(m.group(1))
+        except yaml.YAMLError:
+            return None
+
+    @property
+    def json_schema(self):
+        """Parsed structure from the ``@json`` block in the column comment, or ``None``.
+
+        Returns the YAML structure as a Python object (dict/list/str) when the
+        column comment contains an ``@json`` block::
+
+            @json
+            ```yaml
+            lang: text          # ISO 639-1
+            views: integer
+            tags: [text]
+            items:
+              - id: uuid
+                name: text
+            ```
+
+        Returns ``None`` when no ``@json`` block is present.
+        """
+        return self.__json_schema
+
     def __repr__(self):
         md_ = self.__metadata
         field_constraint = f"{md_['notnull'] and 'NOT NULL' or ''}"
         repr_ = f"({md_['fieldtype']}) {field_constraint}"
         if self.__is_set:
             repr_ = f"{repr_} ({self.__name} {self.__comp} {self.__value})"
-        return repr_.strip()
+        repr_ = repr_.strip()
+        if self.__json_schema is not None:
+            yaml_str = yaml.dump(self.__json_schema, default_flow_style=False, allow_unicode=True)
+            for line in yaml_str.rstrip('\n').splitlines():
+                repr_ += f'\n    {line}'
+        return repr_
 
     def __str__(self):
         return str(self.__value)
@@ -198,12 +280,13 @@ class Field():
         cast = ''
         if self.__value != NULL and not isiterable:
             cast = f'::{self.__sql_type}'
+        rhs = _OPERATOR_RHS_TEMPLATES.get((comp, self.__sql_type), f'{comp_str}{cast}')
         if col_is_array and comp == '=':
             where_repr = f'{comp_str} = ANY({self.__praf(query, ho_id)})'
-        elif not self.unaccent:
-            where_repr = f"{self.__praf(query, ho_id)} {comp} {comp_str}{cast}"
+        elif not self.unaccent or not self._is_text_like:
+            where_repr = f"{self.__praf(query, ho_id)} {comp} {rhs}"
         else:
-            where_repr = f"unaccent({self.__praf(query, ho_id)}) {comp} unaccent({comp_str}{cast})"
+            where_repr = f"unaccent({self.__praf(query, ho_id)}) {comp} unaccent({rhs})"
         return where_repr
 
     def _where_expr(self, query, ho_id):
@@ -239,12 +322,13 @@ class Field():
         cast = ''
         if not is_array_any and self.__value != NULL and not isiterable:
             cast = f'::{self.__sql_type}'
+        placeholder = _OPERATOR_RHS_TEMPLATES.get((comp, self.__sql_type), f'{comp_str}{cast}')
         return FieldExpr(
             column=self.__praf(query, ho_id),
             comp=comp,
-            placeholder=f'{comp_str}{cast}',
+            placeholder=placeholder,
             value=self,
-            unaccent=self.unaccent,
+            unaccent=self.unaccent and self._is_text_like,
             array_any=is_array_any,
         )
 
@@ -314,7 +398,7 @@ class Field():
             self.__comp = '='
             self.__unaccent = False
             return
-        self.__unaccent = unaccent
+        self.unaccent = unaccent
         comp = None
         if isinstance(value, tuple):
             if len(value) != 2:
@@ -376,10 +460,30 @@ class Field():
         """
         return self.__unaccent
 
+    @property
+    def _is_text_like(self):
+        return is_text_like_sql_type(self.__sql_type)
+
     @unaccent.setter
     def unaccent(self, value):
         if not isinstance(value, bool):
             raise RuntimeError('unaccent value must be True or False!')
+        if value and not self._is_text_like:
+            warnings.warn(
+                f"unaccent ignored: field '{self.__name}' has non-text type '{self.__sql_type}'",
+                UserWarning,
+                stacklevel=2,
+            )
+            value = False
+        if value and not self.__relation._ho_model.has_extension('unaccent'):
+            warnings.warn(
+                f"unaccent ignored: the \"unaccent\" PostgreSQL extension is not "
+                f"installed on database '{self.__relation._ho_model._dbname}'. "
+                f"Install it with: CREATE EXTENSION IF NOT EXISTS unaccent;",
+                UserWarning,
+                stacklevel=2,
+            )
+            value = False
         self.__unaccent = value
 
     def _comp(self):

half_orm-1.0.0/half_orm/migrations/BREAKING_CHANGES-1.0.0.md

@@ -0,0 +1,50 @@
+# half-orm 1.0.0 — Breaking Changes
+
+## `ho_get()` returns a `dict` and raises on 0 or >1 rows
+
+`ho_get()` now returns a plain `dict` directly (no longer a Relation
+object).  It raises:
+- `NotFoundError` if no row matches
+- `MultipleRowsError` if more than one row matches
+
+**Before:**
+```python
+obj = MyTable(id=1).ho_get()  # returned a Relation
+```
+
+**After:**
+```python
+row = MyTable(id=1).ho_get()  # returns dict, or raises
+```
+
+The async counterpart `ho_aget()` has been added with the same semantics.
+
+## Deprecated query-builder setters removed
+
+`ho_limit`, `ho_offset`, `ho_order_by`, `ho_distinct` no longer exist as
+property setters.  Pass them as keyword arguments to `ho_select()`.
+
+**Before:**
+```python
+rel.ho_limit = 10
+rel.ho_order_by = "name"
+for row in rel.ho_select():
+    ...
+```
+
+**After:**
+```python
+for row in rel.ho_select(limit=10, order_by="name"):
+    ...
+```
+
+## `FKEYS_PROPERTIES` / `FKEYS` class attributes removed
+
+Use `Fkeys` only.  Any subclass that still defines `FKEYS_PROPERTIES` or
+`FKEYS` will raise an error at class definition time.
+
+## `ho_cast()` raises `CastError` for invalid inheritance targets
+
+`ho_cast(TargetClass)` now raises `half_orm.relation_errors.CastError` if
+`TargetClass` is not in the PostgreSQL inheritance hierarchy of the
+source table.

half_orm-1.0.0/half_orm/migrations/__init__.py

@@ -0,0 +1,29 @@
+"""Migration support for halfORM extensions.
+
+Extensions (e.g. half-orm-dev) use :func:`get_breaking_changes_dir` to locate
+the ``BREAKING_CHANGES-X.Y.Z.md`` files shipped with this package and display
+relevant migration notes when the user upgrades through a breaking version.
+"""
+
+from pathlib import Path
+
+
+def get_breaking_changes_dir() -> Path:
+    """Return the directory containing ``BREAKING_CHANGES-X.Y.Z.md`` files.
+
+    The returned path always points to the ``migrations/`` directory inside
+    the installed ``half_orm`` package, regardless of the installation method
+    (regular install, editable install, virtual environment, etc.).
+
+    Returns:
+        Path: an existing directory; never ``None``.
+
+    Example (in an extension)::
+
+        try:
+            from half_orm.migrations import get_breaking_changes_dir
+            half_orm_migrations = get_breaking_changes_dir()
+        except (ImportError, AttributeError):
+            half_orm_migrations = None   # older half-orm — ignore silently
+    """
+    return Path(__file__).parent