half-orm 1.2.0__tar.gz → 1.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {half_orm-1.2.0/half_orm.egg-info → half_orm-1.2.1}/PKG-INFO +6 -2
  2. {half_orm-1.2.0 → half_orm-1.2.1}/README.md +5 -1
  3. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/field.py +66 -9
  4. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/fkey.py +9 -3
  5. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/model.py +106 -15
  6. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/pg_meta.py +36 -13
  7. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/relation.py +5 -3
  8. half_orm-1.2.1/half_orm/version.txt +1 -0
  9. {half_orm-1.2.0 → half_orm-1.2.1/half_orm.egg-info}/PKG-INFO +6 -2
  10. {half_orm-1.2.0 → half_orm-1.2.1}/pyproject.toml +1 -1
  11. half_orm-1.2.0/half_orm/version.txt +0 -1
  12. {half_orm-1.2.0 → half_orm-1.2.1}/AUTHORS +0 -0
  13. {half_orm-1.2.0 → half_orm-1.2.1}/LICENSE +0 -0
  14. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/__init__.py +0 -0
  15. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/__main__.py +0 -0
  16. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/_predicate.py +0 -0
  17. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/cli.py +0 -0
  18. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/cli_utils.py +0 -0
  19. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/field_errors.py +0 -0
  20. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/hotest.py +0 -0
  21. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/migrations/BREAKING_CHANGES-1.0.0.md +0 -0
  22. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/migrations/__init__.py +0 -0
  23. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/model_errors.py +0 -0
  24. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/null.py +0 -0
  25. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/py.typed +0 -0
  26. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/relation_errors.py +0 -0
  27. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/relation_factory.py +0 -0
  28. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/sql_adapter.py +0 -0
  29. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/sql_ast.py +0 -0
  30. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/testing.py +0 -0
  31. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/transaction.py +0 -0
  32. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm/utils.py +0 -0
  33. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm.egg-info/SOURCES.txt +0 -0
  34. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm.egg-info/dependency_links.txt +0 -0
  35. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm.egg-info/entry_points.txt +0 -0
  36. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm.egg-info/requires.txt +0 -0
  37. {half_orm-1.2.0 → half_orm-1.2.1}/half_orm.egg-info/top_level.txt +0 -0
  38. {half_orm-1.2.0 → half_orm-1.2.1}/setup.cfg +0 -0
  39. {half_orm-1.2.0 → half_orm-1.2.1}/test/test_cli.py +0 -0
  40. {half_orm-1.2.0 → half_orm-1.2.1}/test/test_main.py +0 -0
  41. {half_orm-1.2.0 → half_orm-1.2.1}/test/test_sql_ast.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: half_orm
3
- Version: 1.2.0
3
+ Version: 1.2.1
4
4
  Summary: A database-first ORM for PostgreSQL
5
5
  Author-email: Joël Maïzi <joel.maizi@collorg.org>
6
6
  License-Expression: GPL-3.0-or-later
@@ -81,7 +81,9 @@ with your data. No migrations, no code generation.
81
81
  **The central idea:** a `Relation` object is a **predicate**. It describes the
82
82
  logical condition that rows must satisfy to belong to the relation. Its
83
83
  *extension* — the set of rows currently satisfying the predicate in the
84
- database — is what you read, update, or delete.
84
+ database — is what you read, update, or delete. Why a predicate rather than an
85
+ object mapped to a row is argued in
86
+ [A Relation Is a Predicate, Not an Object](https://half-orm.github.io/half-orm/dev/essays/relation-as-predicate/).
85
87
 
86
88
  ## Key features
87
89
 
@@ -164,6 +166,8 @@ Author(id=alice['id']).ho_delete()
164
166
 
165
167
  - [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
166
168
  - [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
169
+ - [Why database-first](https://half-orm.github.io/half-orm/dev/essays/) — the argument
170
+ behind the design, in six essays
167
171
  - [Breaking changes](https://half-orm.github.io/half-orm/latest/breaking-changes/) — and
168
172
  what to do coming from a 0.x release, all of which were published as Beta
169
173
  - [Security](https://half-orm.github.io/half-orm/latest/security/) — advisories by
@@ -52,7 +52,9 @@ with your data. No migrations, no code generation.
52
52
  **The central idea:** a `Relation` object is a **predicate**. It describes the
53
53
  logical condition that rows must satisfy to belong to the relation. Its
54
54
  *extension* — the set of rows currently satisfying the predicate in the
55
- database — is what you read, update, or delete.
55
+ database — is what you read, update, or delete. Why a predicate rather than an
56
+ object mapped to a row is argued in
57
+ [A Relation Is a Predicate, Not an Object](https://half-orm.github.io/half-orm/dev/essays/relation-as-predicate/).
56
58
 
57
59
  ## Key features
58
60
 
@@ -135,6 +137,8 @@ Author(id=alice['id']).ho_delete()
135
137
 
136
138
  - [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
137
139
  - [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
140
+ - [Why database-first](https://half-orm.github.io/half-orm/dev/essays/) — the argument
141
+ behind the design, in six essays
138
142
  - [Breaking changes](https://half-orm.github.io/half-orm/latest/breaking-changes/) — and
139
143
  what to do coming from a 0.x release, all of which were published as Beta
140
144
  - [Security](https://half-orm.github.io/half-orm/latest/security/) — advisories by
@@ -10,6 +10,7 @@ import warnings
10
10
  import yaml
11
11
  from collections.abc import Iterable
12
12
  from half_orm.null import NULL
13
+ from half_orm.pg_meta import quote_ident
13
14
  from half_orm.sql_adapter import SQL_ADAPTER
14
15
  from half_orm.sql_ast import FieldExpr
15
16
 
@@ -93,6 +94,32 @@ def check_comparator(comp: str) -> str:
93
94
  f"'=', '!=', '<', '>=', '@>', '@@'.")
94
95
 
95
96
 
97
+ # A type name PostgreSQL reads the same bare or quoted. Anything else -- an
98
+ # upper-case letter, a space, a quote, a semicolon -- is quoted before it is
99
+ # written into a cast.
100
+ _BARE_TYPE_NAME_RE = re.compile(r'^[a-z_][a-z0-9_]*$')
101
+
102
+
103
+ def _cast_to(sql_type: str) -> str:
104
+ """Render the ``::type`` cast applied to a bound value.
105
+
106
+ The type name is read from the catalog and interpolated, no parameter
107
+ being able to stand for it. PostgreSQL lets a user-defined type be called
108
+ anything -- ``create type "int4); drop table t; --"`` is legal -- so a
109
+ name that is not a plain lower-case identifier is quoted, and can then
110
+ only ever be read as a name. Plain ones are left bare, which keeps the
111
+ statements for every built-in type exactly as they were.
112
+ """
113
+ if _BARE_TYPE_NAME_RE.match(sql_type):
114
+ return f'::{sql_type}'
115
+ return f'::{quote_ident(sql_type)}'
116
+
117
+
118
+ # What IS / IS NOT may be followed by. They take a keyword, not a value, so
119
+ # none of this can be bound as a parameter.
120
+ _IS_OPERANDS = {True: 'TRUE', False: 'FALSE'}
121
+
122
+
96
123
  class Expr:
97
124
  """A raw SQL expression for use with :meth:`Field.set`.
98
125
 
@@ -313,9 +340,17 @@ class Field():
313
340
  select. Otherwise, returns the field name quoted with ".
314
341
  """
315
342
  ho_id = f'r{ho_id}'
343
+ # quote_ident, not a bare pair of quotes: a column may be called
344
+ # `a"b`, and the quote inside it would otherwise close the identifier.
316
345
  if query == 'select':
317
- return f'{ho_id}."{self.__name}"'
318
- return f'"{self.__name}"'
346
+ return f'{ho_id}.{quote_ident(self.__name)}'
347
+ return quote_ident(self.__name)
348
+
349
+ def __is_operand(self):
350
+ """The keyword following IS / IS NOT for the current value."""
351
+ if self.__value is NULL:
352
+ return 'NULL'
353
+ return _IS_OPERANDS[self.__value]
319
354
 
320
355
  def _where_repr(self, query, ho_id):
321
356
  """Returns the SQL representation of the field for the where clause
@@ -329,9 +364,11 @@ class Field():
329
364
  comp = 'in'
330
365
  cast = ''
331
366
  if self.__value != NULL and not isiterable:
332
- cast = f'::{self.__sql_type}'
367
+ cast = _cast_to(self.__sql_type)
333
368
  rhs = _OPERATOR_RHS_TEMPLATES.get((comp, self.__sql_type), f'{comp_str}{cast}')
334
- if col_is_array and comp == '=':
369
+ if comp in ('is', 'is not'):
370
+ where_repr = f"{self.__praf(query, ho_id)} {comp} {self.__is_operand()}"
371
+ elif col_is_array and comp == '=':
335
372
  where_repr = f'{comp_str} = ANY({self.__praf(query, ho_id)})'
336
373
  elif not self.unaccent or not self._is_text_like:
337
374
  where_repr = f"{self.__praf(query, ho_id)} {comp} {rhs}"
@@ -366,12 +403,21 @@ class Field():
366
403
  isiterable = type(self.__value) in {tuple, list, set}
367
404
  col_is_array = self.__sql_type[0] == '_'
368
405
  comp = self._comp()
406
+ if comp in ('is', 'is not'):
407
+ # A keyword, written into the statement: `IS %s` is not SQL.
408
+ return FieldExpr(
409
+ column=self.__praf(query, ho_id),
410
+ comp=comp,
411
+ placeholder='',
412
+ value=None,
413
+ col_ref=self.__is_operand(),
414
+ )
369
415
  if comp == '=' and isiterable:
370
416
  comp = 'in'
371
417
  is_array_any = col_is_array and comp == '='
372
418
  cast = ''
373
419
  if not is_array_any and self.__value != NULL and not isiterable:
374
- cast = f'::{self.__sql_type}'
420
+ cast = _cast_to(self.__sql_type)
375
421
  placeholder = _OPERATOR_RHS_TEMPLATES.get((comp, self.__sql_type), f'{comp_str}{cast}')
376
422
  return FieldExpr(
377
423
  column=self.__praf(query, ho_id),
@@ -407,7 +453,8 @@ class Field():
407
453
  ``=``. Supported comparators: ``=``, ``!=``, ``<``, ``<=``,
408
454
  ``>``, ``>=``, ``like``, ``not like``, ``ilike``, ``not ilike``,
409
455
  ``similar to``, ``not similar to``, ``in``, ``not in``, ``is``,
410
- ``is not``, ``is distinct from``, ``is not distinct from``, and
456
+ ``is not`` (with ``NULL``, ``True`` or ``False`` only),
457
+ ``is distinct from``, ``is not distinct from``, and
411
458
  any operator spelled with PostgreSQL's operator characters —
412
459
  including those added by extensions, such as ``@@``, ``@>``,
413
460
  ``&&`` or pgvector's ``<->``.
@@ -496,6 +543,15 @@ class Field():
496
543
  value = tuple(value)
497
544
  if value is NULL and comp not in {'is', 'is not'}:
498
545
  raise ValueError("comp should be 'is' or 'is not' with NULL value!")
546
+ if comp in {'is', 'is not'} and value is not NULL \
547
+ and not isinstance(value, bool):
548
+ # Whatever the value, the condition used to be rendered as
549
+ # `IS NULL`: ('is', True) silently selected the rows where the
550
+ # column was NULL instead of those where it was true.
551
+ raise ValueError(
552
+ f"'{comp}' takes NULL, True or False, got {value!r}. Use "
553
+ "'is distinct from' / 'is not distinct from' to compare "
554
+ "with a value.")
499
555
  self.__is_set = True
500
556
  self.__value = value
501
557
  self.__comp = comp
@@ -552,9 +608,10 @@ class Field():
552
608
 
553
609
  def _comp(self):
554
610
  "Returns the comparator associated to the value."
555
- if self.__comp == '%':
556
- return '%%'
557
- return self.__comp
611
+ # Doubled wherever it appears, not only when it is the whole
612
+ # operator: pg_trgm's `%>` and `<%` reached psycopg as a malformed
613
+ # placeholder.
614
+ return self.__comp.replace('%', '%%')
558
615
 
559
616
  @property
560
617
  def _relation(self):
@@ -11,7 +11,7 @@ FKs. They are exposed as attributes on relation instances and used in two ways:
11
11
  * **``.set(rel)``** to add a JOIN condition on the owning relation.
12
12
  """
13
13
 
14
- from half_orm.pg_meta import normalize_fqrn, normalize_qrn
14
+ from half_orm.pg_meta import normalize_fqrn, normalize_qrn, quote_ident, unquote_ident
15
15
  from half_orm import utils
16
16
 
17
17
  def _would_create_cycle(from_rel, to_rel):
@@ -79,7 +79,10 @@ class FKey:
79
79
  self.__confdeltype = confdeltype
80
80
  self.__fk_fqrn = fk_sfqrn
81
81
  self.__fields_names = fields
82
- self.__fields = [f'"{name}"' for name in fields]
82
+ # Unquoted first: navigating a key hands the reverse one names that
83
+ # are already quoted. Then quoted properly, a bare pair of quotes
84
+ # leaving a quote inside the name free to close the identifier.
85
+ self.__fields = [quote_ident(unquote_ident(name)) for name in fields]
83
86
 
84
87
  def __get_rel(self, fqtn):
85
88
  """Returns the relation class referenced by fqtn.
@@ -223,7 +226,10 @@ class FKey:
223
226
  if from_._qrn == orig_rel._qrn:
224
227
  from_id = orig_rel_id
225
228
  from_fields = (f'{from_id}.{name}' for name in self.__fields)
226
- to_fields = (f'{to_id}.{name}' for name in self.__fk_names)
229
+ # Quoted here: the names read from the catalog arrive bare, and
230
+ # went into the join condition as they were.
231
+ to_fields = (f'{to_id}.{quote_ident(unquote_ident(name))}'
232
+ for name in self.__fk_names)
227
233
  bounds = " and ".join(
228
234
  [f'{a} = {b}' for a, b in zip(to_fields, from_fields)])
229
235
  return f"({bounds})"
@@ -262,8 +262,9 @@ class Model:
262
262
  never written to the logs, in any mode — but extensions do:
263
263
  half_orm_dev makes a server read-only when it is set.
264
264
 
265
- ``crud_only`` refuses :meth:`execute_query` and
266
- :meth:`aexecute_query`, leaving only the Relation CRUD methods.
265
+ ``crud_only`` refuses :meth:`execute_query`,
266
+ :meth:`execute_function`, :meth:`call_procedure` and their async
267
+ variants, leaving only the Relation CRUD methods.
267
268
  It is a guard rail against accidents, not a privilege boundary:
268
269
  use ``GRANT``/``REVOKE`` to actually restrict what a role can do.
269
270
  scope (str | None): package name used to resolve registered subclasses.
@@ -287,8 +288,15 @@ class Model:
287
288
  MalformedConfigFile: if ``name`` is missing from the file.
288
289
  psycopg.OperationalError: if the database connection fails.
289
290
  """
290
- __deja_vu = {}
291
- _classes_ = {}
291
+ # Models and relation classes are shared between the Model objects that
292
+ # reach the same database *as the same role*: (host, port, dbname, user),
293
+ # read off the connection. They used to be shared by database name alone,
294
+ # so a second Model opened on the same database under another role -- a
295
+ # read-only one next to an administrative one -- was handed the classes of
296
+ # the first, and ran its queries through the first one's connection.
297
+ __deja_vu = {} # identity -> Model
298
+ __registries = {} # identity -> {dbname: {fqrn: relation class}}
299
+ __first_seen = {} # dbname -> Model, for the _deja_vu() lookup by name
292
300
  __sql_trace = False
293
301
  def __init__(self, config_file: None, scope: str=None, with_half_orm_meta=False):
294
302
  self.__connection_params = {}
@@ -300,8 +308,42 @@ class Model:
300
308
  self.__schema_generation = 0
301
309
  self.__read_sets = {}
302
310
  self.__aconn = None
311
+ self.__identity = None
303
312
  self.__connect()
304
313
 
314
+ @property
315
+ def _classes_(self):
316
+ """The relation classes registered for this Model's connection identity.
317
+
318
+ ``{dbname: {(dbname, schema, relation): class}}``, shared by every
319
+ Model connected to the same database as the same role, and by no
320
+ other.
321
+ """
322
+ return Model.__registries.setdefault(self.__identity, {})
323
+
324
+ def __set_identity(self, conn):
325
+ """Record who this Model is connected as, and where.
326
+
327
+ Taken from the connection rather than from the configuration: an
328
+ omitted host, port or user is resolved by libpq, and only the result
329
+ says whether two Models may answer for one another.
330
+
331
+ ``reconnect(config_file)`` may change the role. The classes already
332
+ generated stay bound to this Model -- that is what reconnecting a
333
+ Model means -- so their registry follows it, and the identity it
334
+ leaves stops designating it.
335
+ """
336
+ info = conn.info
337
+ identity = (info.host, info.port, info.dbname, info.user)
338
+ previous = self.__identity
339
+ if previous is not None and previous != identity \
340
+ and Model.__deja_vu.get(previous) is self:
341
+ del Model.__deja_vu[previous]
342
+ registry = Model.__registries.pop(previous, None)
343
+ if registry is not None and identity not in Model.__deja_vu:
344
+ Model.__registries[identity] = registry
345
+ self.__identity = identity
346
+
305
347
  def has_extension(self, name: str) -> bool:
306
348
  """True if the PostgreSQL extension `name` is installed on this database.
307
349
 
@@ -422,15 +464,17 @@ class Model:
422
464
  conn.adapters.register_dumper(Field, FieldDumper)
423
465
  conn.adapters.register_dumper(dict, JsonbDumper)
424
466
  self.__pg_meta = pg_meta.PgMeta(conn, self.__with_half_orm_meta, reload)
467
+ self.__set_identity(conn)
425
468
  if reload:
426
469
  self.__schema_generation += 1
427
470
  self.__read_sets = {}
428
471
  self._classes_[self._dbname] = {}
429
- self.__deja_vu[self.__dbname] = self
472
+ Model.__deja_vu[self.__identity] = self
473
+ Model.__first_seen[self.__dbname] = self
430
474
  self.__thread_local.conn = conn
431
475
  self.__thread_local.schema_generation = self.__schema_generation
432
- if self.__dbname not in self.__class__.__deja_vu:
433
- self.__deja_vu[self.__dbname] = self
476
+ Model.__deja_vu.setdefault(self.__identity, self)
477
+ Model.__first_seen.setdefault(self.__dbname, self)
434
478
 
435
479
  reconnect = __connect
436
480
 
@@ -572,17 +616,19 @@ class Model:
572
616
  if len(parts) < 2:
573
617
  raise model_errors.MissingSchemaInName(relation_name)
574
618
  schema, table = '.'.join(parts[:-1]), parts[-1]
575
- return factory({'fqrn': (self.__dbname, schema, table), 'model': self.__deja_vu[self.__dbname], 'fields_aliases':fields_aliases})
619
+ return factory({'fqrn': (self.__dbname, schema, table), 'model': Model.__deja_vu[self.__identity], 'fields_aliases':fields_aliases})
576
620
 
577
621
 
578
622
  @staticmethod
579
623
  def _deja_vu(dbname):
580
624
  """Returns None if the database hasn't been loaded yet.
581
- Otherwise, it returns the Model object already loaded.
582
- The Model object is shared between all_ the relations in the
583
- database. The Model object is loaded only once for a given database.
625
+ Otherwise, it returns the first Model object loaded for that name.
626
+
627
+ A name does not say which server or which role: relation classes are
628
+ shared per connection identity (see ``_classes_``), and this lookup
629
+ is not what binds them to a Model.
584
630
  """
585
- return Model.__deja_vu.get(dbname)
631
+ return Model.__first_seen.get(dbname)
586
632
 
587
633
  @property
588
634
  def __dbname(self):
@@ -672,12 +718,20 @@ class Model:
672
718
  f"Query execution failed:\nquery: {query}\n"
673
719
  f"values: {_describe_values(values)}\n")
674
720
 
721
+ # See _execute_query: a connection lost inside a transaction is not
722
+ # replaced behind the caller's back, the retry would commit on its own.
723
+ in_transaction = self.__aconn is not None and not self.__aconn.autocommit
675
724
  if self.__aconn is not None and self.__aconn.closed:
725
+ if in_transaction:
726
+ raise psycopg.OperationalError(
727
+ "the connection was lost inside a transaction")
676
728
  await self.aconnect()
677
729
  try:
678
730
  cursor = self._aconnection.cursor(row_factory=dict_row)
679
731
  await cursor.execute(query, values)
680
732
  except (psycopg.OperationalError, psycopg.InterfaceError):
733
+ if in_transaction:
734
+ raise
681
735
  await self.aconnect()
682
736
  try:
683
737
  cursor = self._aconnection.cursor(row_factory=dict_row)
@@ -853,13 +907,23 @@ class Model:
853
907
  def _execute_query(self, query, values=None, mogrify=False):
854
908
  """Internal query executor — no crud_only check. Called by Relation.__execute."""
855
909
  values = self._unwrap_values(values)
856
- cursor = self._connection.cursor(row_factory=dict_row)
910
+ conn = self._connection
911
+ # Read before the query runs: once the connection is lost there is
912
+ # no asking it whether a transaction was open.
913
+ in_transaction = not conn.autocommit
914
+ cursor = conn.cursor(row_factory=dict_row)
857
915
  try:
858
916
  if mogrify or self.sql_trace:
859
917
  client_cur = ClientCursor(self._connection)
860
918
  print(client_cur.mogrify(query, values))
861
919
  cursor.execute(query, values)
862
920
  except (psycopg.OperationalError, psycopg.InterfaceError):
921
+ if in_transaction:
922
+ # The statements already sent went with the connection.
923
+ # Replaying this one on a fresh connection would run it in
924
+ # autocommit mode -- committed on its own, outside the
925
+ # transaction the caller believes it is part of.
926
+ raise
863
927
  self.ping()
864
928
  cursor = self._connection.cursor(row_factory=dict_row)
865
929
  cursor.execute(query, values)
@@ -872,6 +936,12 @@ class Model:
872
936
  raise exc
873
937
  return cursor
874
938
 
939
+ def __check_not_crud_only(self):
940
+ """Refuse direct SQL when the connection is declared `crud_only`."""
941
+ if self._crud_only:
942
+ raise PermissionError(
943
+ "Direct SQL execution is disabled (crud_only = true in connection config).")
944
+
875
945
  def execute_query(self, query, values=None, mogrify=False):
876
946
  """Execute a raw SQL query. *Executes SQL.*
877
947
 
@@ -909,12 +979,16 @@ class Model:
909
979
 
910
980
  Raises:
911
981
  RuntimeError: if both ``*args`` and ``**kwargs`` are provided.
982
+ PermissionError: if ``crud_only`` is set in the connection configuration.
912
983
  ValueError: if the name or a named parameter is not a SQL
913
984
  identifier. The name is interpolated into the statement,
914
985
  unlike the arguments, which are bound.
915
986
  """
916
987
  if bool(args) and bool(kwargs):
917
988
  raise RuntimeError("You can't mix args and kwargs with the execute_function method!")
989
+ # As the async variant always did, going through aexecute_query: a
990
+ # function is arbitrary SQL, not one of the Relation CRUD methods.
991
+ self.__check_not_crud_only()
918
992
  fct_name = _check_qualified_name(fct_name, 'function name')
919
993
  _check_named_params(kwargs, 'execute_function')
920
994
  cursor = self._connection.cursor(row_factory=dict_row)
@@ -941,12 +1015,14 @@ class Model:
941
1015
 
942
1016
  Raises:
943
1017
  RuntimeError: if both ``*args`` and ``**kwargs`` are provided.
1018
+ PermissionError: if ``crud_only`` is set in the connection configuration.
944
1019
  ValueError: if the name or a named parameter is not a SQL
945
1020
  identifier. The name is interpolated into the statement,
946
1021
  unlike the arguments, which are bound.
947
1022
  """
948
1023
  if bool(args) and bool(kwargs):
949
1024
  raise RuntimeError("You can't mix args and kwargs with the call_procedure method!")
1025
+ self.__check_not_crud_only()
950
1026
  proc_name = _check_qualified_name(proc_name, 'procedure name')
951
1027
  _check_named_params(kwargs, 'call_procedure')
952
1028
  if kwargs:
@@ -1126,11 +1202,26 @@ class Model:
1126
1202
  # imported modules, so get_relation_class() alone could go
1127
1203
  # stale. Fall back to it only when there's no generated
1128
1204
  # package to import from, or its conventional class is missing.
1205
+ module_path = f'{package_name}.{module_name}'
1206
+ if not all(part.isidentifier() for part in module_path.split('.')):
1207
+ # As in _import_class: nothing importable can be named
1208
+ # this, and these names come out of the database. A
1209
+ # schema called `..x` would otherwise turn the import
1210
+ # below into a relative one climbing out of the package.
1211
+ yield self.get_relation_class(module_name), relation[0]
1212
+ continue
1129
1213
  try:
1130
1214
  class_name = pg_meta.camel_case(relation[1][-1])
1131
- module = importlib.import_module(f".{module_name}", package_name)
1215
+ module = importlib.import_module(module_path)
1132
1216
  yield getattr(module, class_name), relation[0]
1133
- except (ModuleNotFoundError, AttributeError):
1217
+ except ModuleNotFoundError as exc:
1218
+ if not _module_is_absent(exc, module_path):
1219
+ # The module is there; something it imports is not.
1220
+ # That is a defect in the caller's own code, which
1221
+ # falling back to the generated class would hide.
1222
+ raise
1223
+ yield self.get_relation_class(module_name), relation[0]
1224
+ except AttributeError:
1134
1225
  yield self.get_relation_class(module_name), relation[0]
1135
1226
 
1136
1227
  @property
@@ -58,6 +58,17 @@ def quote_ident(name) -> str:
58
58
  """
59
59
  return '"' + str(name).replace('"', '""') + '"'
60
60
 
61
+ def unquote_ident(name) -> str:
62
+ """Undo quote_ident; a bare name is returned unchanged.
63
+
64
+ Only a fully quoted name is unwrapped: `first_name"` is not one, and
65
+ comes back as it went in.
66
+ """
67
+ name = str(name)
68
+ if len(name) >= 2 and name.startswith('"') and name.endswith('"'):
69
+ return name[1:-1].replace('""', '"')
70
+ return name
71
+
61
72
  def normalize_fqrn(t_fqrn: tuple) -> str:
62
73
  """
63
74
  Transform the tuple (<db name>, <schema name>, <table name>) in
@@ -198,13 +209,16 @@ ORDER BY
198
209
  class _Meta(dict):
199
210
  __d_meta = {}
200
211
 
212
+ # Keyed by (host, port, dbname), not by dbname alone: two servers may
213
+ # each hold a database of the same name, and answering one with the
214
+ # catalog of the other describes relations it does not have.
201
215
  @classmethod
202
- def deja_vu(cls, dbname):
203
- return dbname in cls.__d_meta
216
+ def deja_vu(cls, key):
217
+ return key in cls.__d_meta
204
218
 
205
219
  @classmethod
206
- def register(cls, dbname, meta):
207
- cls.__d_meta[dbname] = meta
220
+ def register(cls, key, meta):
221
+ cls.__d_meta[key] = meta
208
222
 
209
223
  def __getitem__(self, key):
210
224
  return _Meta.__d_meta.__getitem__(key)
@@ -228,9 +242,15 @@ class PgMeta:
228
242
  reload (bool, optional): A flag indicating whether to reload the metadata from the database. \
229
243
  Defaults to False.
230
244
  """
231
- self.__dbname = connection.info.get_parameters()['dbname']
245
+ info = connection.info
246
+ self.__dbname = info.get_parameters()['dbname']
247
+ # What the connection actually reached, rather than what the
248
+ # configuration asked for: an omitted host or port is resolved by
249
+ # libpq from the environment, and only the result tells two servers
250
+ # apart.
251
+ self.__key = (info.host, info.port, self.__dbname)
232
252
  self.__with_half_orm_meta = with_half_orm_meta
233
- if not PgMeta.meta.deja_vu(self.__dbname) or reload:
253
+ if not PgMeta.meta.deja_vu(self.__key) or reload:
234
254
  self.__load_metadata(connection)
235
255
 
236
256
  def __meta_allowed(self, schema, relname):
@@ -243,15 +263,18 @@ class PgMeta:
243
263
  return f'{schema}.{relname}' in allow
244
264
 
245
265
  def metadata(self, dbname):
246
- """Retrieves the metadata for the specified database name.
266
+ """Retrieves the metadata of the database this instance was built on.
247
267
 
248
268
  Args:
249
- dbname (str): The name of the PostgreSQL database.
269
+ dbname (str): The name of the PostgreSQL database. Kept for the
270
+ signature every accessor here shares; the lookup goes
271
+ through the server the connection reached, since a name
272
+ alone does not identify a database.
250
273
 
251
274
  Returns:
252
- dict: The metadata of the specified database.
275
+ dict: The metadata of the database.
253
276
  """
254
- return self.meta[dbname]
277
+ return self.meta[self.__key]
255
278
 
256
279
  def relations_list(self, dbname):
257
280
  """Retrieves a list of relations for the specified database.
@@ -348,7 +371,7 @@ class PgMeta:
348
371
  table_key, fields, ffields, confupdtype, confdeltype, True, is_singleton)
349
372
 
350
373
  metadata['relations_list'].sort()
351
- PgMeta.meta.register(self.__dbname, metadata)
374
+ PgMeta.meta.register(self.__key, metadata)
352
375
 
353
376
  def has_relation(self, dbname, schema, relation):
354
377
  """Checks whether the specified relation exists in the specified database.
@@ -361,7 +384,7 @@ class PgMeta:
361
384
  Returns:
362
385
  bool: True if the relation exists, False otherwise.
363
386
  """
364
- return (dbname, schema, relation) in self.meta[dbname]['byname']
387
+ return (dbname, schema, relation) in self.metadata(dbname)['byname']
365
388
 
366
389
  def has_extension(self, dbname, name):
367
390
  """Checks whether the specified PostgreSQL extension is installed.
@@ -373,7 +396,7 @@ class PgMeta:
373
396
  Returns:
374
397
  bool: True if the extension is installed, False otherwise.
375
398
  """
376
- return name in self.meta[dbname]['extensions']
399
+ return name in self.metadata(dbname)['extensions']
377
400
 
378
401
 
379
402
  def desc(self, dbname):
@@ -472,7 +472,8 @@ class Relation:
472
472
  placeholders += fk_query
473
473
  values += fk_values
474
474
  returning = args or ['*']
475
- pk_cols = [f'"{n}"' for n in self._ho_pkey] if upsert else None
475
+ pk_cols = ([_ho_quote_ident(field.name) for field in self._ho_pkey.values()]
476
+ if upsert else None)
476
477
  stmt = ASTInsert(
477
478
  table=self._qrn,
478
479
  columns=fields_names,
@@ -923,7 +924,7 @@ class Relation:
923
924
  set_clause = []
924
925
  for field_name, new_value in update_args.items():
925
926
  col_name = self._ho_fields[field_name].name
926
- set_clause.append((f'"{col_name}" = %s', new_value))
927
+ set_clause.append((f'{_ho_quote_ident(col_name)} = %s', new_value))
927
928
  if self._ho_join_to:
928
929
  # Build a subquery to avoid any DB round-trip and to correctly
929
930
  # propagate JOIN constraints into the UPDATE predicate.
@@ -2344,7 +2345,8 @@ Fkeys = {"""
2344
2345
  """
2345
2346
  set_fields = self.__get_set_fields()
2346
2347
  fields_names = [
2347
- f'"{field.name}"' for field in self._ho_fields.values() if field.is_set()]
2348
+ _ho_quote_ident(field.name)
2349
+ for field in self._ho_fields.values() if field.is_set()]
2348
2350
  fk_fields = []
2349
2351
  fk_queries = ''
2350
2352
  fk_values = []
@@ -0,0 +1 @@
1
+ 1.2.1
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: half_orm
3
- Version: 1.2.0
3
+ Version: 1.2.1
4
4
  Summary: A database-first ORM for PostgreSQL
5
5
  Author-email: Joël Maïzi <joel.maizi@collorg.org>
6
6
  License-Expression: GPL-3.0-or-later
@@ -81,7 +81,9 @@ with your data. No migrations, no code generation.
81
81
  **The central idea:** a `Relation` object is a **predicate**. It describes the
82
82
  logical condition that rows must satisfy to belong to the relation. Its
83
83
  *extension* — the set of rows currently satisfying the predicate in the
84
- database — is what you read, update, or delete.
84
+ database — is what you read, update, or delete. Why a predicate rather than an
85
+ object mapped to a row is argued in
86
+ [A Relation Is a Predicate, Not an Object](https://half-orm.github.io/half-orm/dev/essays/relation-as-predicate/).
85
87
 
86
88
  ## Key features
87
89
 
@@ -164,6 +166,8 @@ Author(id=alice['id']).ho_delete()
164
166
 
165
167
  - [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
166
168
  - [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
169
+ - [Why database-first](https://half-orm.github.io/half-orm/dev/essays/) — the argument
170
+ behind the design, in six essays
167
171
  - [Breaking changes](https://half-orm.github.io/half-orm/latest/breaking-changes/) — and
168
172
  what to do coming from a 0.x release, all of which were published as Beta
169
173
  - [Security](https://half-orm.github.io/half-orm/latest/security/) — advisories by
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta:__legacy__"
4
4
 
5
5
  [project]
6
6
  name = "half_orm"
7
- version = "1.2.0"
7
+ version = "1.2.1"
8
8
  description = "A database-first ORM for PostgreSQL"
9
9
  readme = "README.md"
10
10
  license = "GPL-3.0-or-later"
@@ -1 +0,0 @@
1
- 1.2.0
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes