strawberry-django-aggregates 0.2.1__tar.gz

strawberry_django_aggregates-0.2.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, the strawberry-django-aggregates maintainers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

strawberry_django_aggregates-0.2.1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: strawberry-django-aggregates
+Version: 0.2.1
+Summary: Hasura-shape aggregations over Django querysets in Strawberry GraphQL — count, sum, avg, min, max, stddev, variance, array_agg + Odoo-grade group-by with timezone-correct date bucketing.
+Author: strawberry-django-aggregates maintainers
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/Apexive/strawberry-django-aggregates
+Project-URL: Documentation, https://github.com/Apexive/strawberry-django-aggregates/blob/main/docs/SPEC.md
+Project-URL: Issues, https://github.com/Apexive/strawberry-django-aggregates/issues
+Keywords: django,strawberry,graphql,aggregate,groupby,hasura,postgraphile,odoo,analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=6.0
+Requires-Dist: strawberry-graphql>=0.315.0
+Requires-Dist: strawberry-graphql-django>=0.82.0
+Provides-Extra: postgres
+Dynamic: license-file
+
+# strawberry-django-aggregates
+
+Hasura-shape aggregations over Django querysets in Strawberry GraphQL.
+
+`count` · `count_distinct` · `sum` · `avg` · `min` · `max` · `stddev` · `variance` · `bool_and` · `bool_or` · `array_agg` · `string_agg` — composed with multi-level `group_by`, `having` filters, and ordering on aggregate aliases. Inspired by [Hasura](https://hasura.io/docs/latest/api-reference/graphql-api/query/#aggregateobject)'s `<table>_aggregate`, [PostGraphile](https://github.com/graphile/pg-aggregates)'s `pg-aggregates`, and [Odoo 18](https://github.com/odoo/odoo/blob/18.0/odoo/models.py)'s `_read_group`. Built for [`strawberry-django`](https://strawberry-django.readthedocs.io) over PostgreSQL and SQLite.
+
+```python
+from decimal import Decimal
+from datetime import datetime
+from strawberry import auto
+import strawberry, strawberry_django
+from strawberry_django_aggregates import AggregateBuilder
+
+from .models import Order
+
+@strawberry_django.type(Order)
+class OrderType:
+    id: auto
+    customer: "CustomerType"
+    total: Decimal
+    status: str
+    created_at: datetime
+
+# One call wires count/sum/avg/min/max + group_by + having into the schema:
+order_aggs = AggregateBuilder(
+    model=Order,
+    aggregate_fields=["total"],
+    group_by_fields=["customer", "status", "created_at"],
+).build()
+
+@strawberry.type
+class Query:
+    orders_aggregate = order_aggs.aggregate_field
+    orders_group_by  = order_aggs.group_by_field
+```
+
+Generates a fully-typed GraphQL surface:
+
+```graphql
+type Query {
+  ordersAggregate(filter: OrderFilter): OrderAggregate!
+  ordersGroupBy(
+    filter:    OrderFilter
+    groupBy:   [OrderGroupBySpec!]!
+    having:    OrderHaving
+    orderBy:   [OrderGroupOrder!]
+    pagination: OffsetPagination
+  ): OrderGroupedResult!
+}
+
+type OrderAggregate {
+  count:           Int!
+  countDistinct(field: OrderCountableField!): Int!
+  sum:             OrderSumFields
+  avg:             OrderAvgFields
+  min:             OrderMinFields
+  max:             OrderMaxFields
+  stddev:          OrderStddevFields    # Postgres only
+  variance:        OrderVarianceFields  # Postgres only
+}
+
+type OrderGrouped {
+  key:   OrderGroupKey!   # composite — every requested groupBy field present
+  count: Int!
+  sum:   OrderSumFields
+  # ... no recursive subgroups field — flat results
+}
+```
+
+## Features
+
+- **Hasura-canonical schema shape.** `<Model>Aggregate { count, countDistinct, sum, avg, min, max, stddev, variance, boolAnd, boolOr, arrayAgg, stringAgg }`.
+- **Odoo-grade group-by.** Multi-level via composite keys (flat result rows), dual date-granularity tracks (`date_trunc` returning `DateTime` AND `date_part::int` returning `Int`), timezone-correct bucketing.
+- **HAVING with aggregate aliases.** `{ countGt: 5, sumTotalGt: 1000 }` — typed inputs generated per measure.
+- **Ordering on aggregates.** `[{ field: "total:sum", direction: DESC }]` — fail-loud on unknown terms (Odoo's pre-17 silent-drop bug avoided).
+- **Standalone backend primitive.** `compute_aggregation(qs, group_by, aggregates, having, order_by, ...)` is callable from any Python context — DRF view, Celery task, admin script, MCP tool — not just GraphQL resolvers.
+- **Determinism.** Type generation produces byte-identical SDL for the same inputs.
+- **No magic.** Every operator, every granularity, every type is whitelisted.
+
+## Non-goals
+
+- **Cross-database aggregation.** PostgreSQL + SQLite only. SQLite degrades gracefully on `array_agg`/`string_agg`/`stddev`/`variance` — those operators raise `OperatorNotSupportedError` at resolver entry.
+- **Auto-traversal of one-to-many / many-to-many for measures.** This is the silent row-multiplication footgun [Odoo refuses to ship](https://github.com/odoo/odoo/blob/18.0/odoo/models.py); we follow. `array_agg` is the explicit escape hatch.
+- **Permission integration.** The library expects a pre-scoped queryset — the caller has already applied `accessible_by(user)` or equivalent. This keeps the library compatible with django-guardian, django-rules, [django-rebac](#) (when shipped), or hand-rolled permission systems.
+
+## Status
+
+Beta (v0.2.1). The schema shape, operator vocabulary, and `compute_aggregation` signature are stable for early adopters, but minor-level iteration is still expected before a 1.0 stability commitment — see [`docs/SPEC.md`](./docs/SPEC.md) § 16. Runtime: Python 3.13, Django 6.0.
+
+## Documentation
+
+- Full contract: [`docs/SPEC.md`](./docs/SPEC.md) — operator catalog, granularity tracks, HAVING semantics, ordering rules, timezone handling, and the Odoo-derived footgun audit.
+- Naming and wire vocabulary: [`docs/TERMINOLOGY.md`](./docs/TERMINOLOGY.md)
+- Contributor quality gate: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
+
+## License
+
+BSD-3-Clause.

strawberry_django_aggregates-0.2.1/README.md

@@ -0,0 +1,98 @@
+# strawberry-django-aggregates
+
+Hasura-shape aggregations over Django querysets in Strawberry GraphQL.
+
+`count` · `count_distinct` · `sum` · `avg` · `min` · `max` · `stddev` · `variance` · `bool_and` · `bool_or` · `array_agg` · `string_agg` — composed with multi-level `group_by`, `having` filters, and ordering on aggregate aliases. Inspired by [Hasura](https://hasura.io/docs/latest/api-reference/graphql-api/query/#aggregateobject)'s `<table>_aggregate`, [PostGraphile](https://github.com/graphile/pg-aggregates)'s `pg-aggregates`, and [Odoo 18](https://github.com/odoo/odoo/blob/18.0/odoo/models.py)'s `_read_group`. Built for [`strawberry-django`](https://strawberry-django.readthedocs.io) over PostgreSQL and SQLite.
+
+```python
+from decimal import Decimal
+from datetime import datetime
+from strawberry import auto
+import strawberry, strawberry_django
+from strawberry_django_aggregates import AggregateBuilder
+
+from .models import Order
+
+@strawberry_django.type(Order)
+class OrderType:
+    id: auto
+    customer: "CustomerType"
+    total: Decimal
+    status: str
+    created_at: datetime
+
+# One call wires count/sum/avg/min/max + group_by + having into the schema:
+order_aggs = AggregateBuilder(
+    model=Order,
+    aggregate_fields=["total"],
+    group_by_fields=["customer", "status", "created_at"],
+).build()
+
+@strawberry.type
+class Query:
+    orders_aggregate = order_aggs.aggregate_field
+    orders_group_by  = order_aggs.group_by_field
+```
+
+Generates a fully-typed GraphQL surface:
+
+```graphql
+type Query {
+  ordersAggregate(filter: OrderFilter): OrderAggregate!
+  ordersGroupBy(
+    filter:    OrderFilter
+    groupBy:   [OrderGroupBySpec!]!
+    having:    OrderHaving
+    orderBy:   [OrderGroupOrder!]
+    pagination: OffsetPagination
+  ): OrderGroupedResult!
+}
+
+type OrderAggregate {
+  count:           Int!
+  countDistinct(field: OrderCountableField!): Int!
+  sum:             OrderSumFields
+  avg:             OrderAvgFields
+  min:             OrderMinFields
+  max:             OrderMaxFields
+  stddev:          OrderStddevFields    # Postgres only
+  variance:        OrderVarianceFields  # Postgres only
+}
+
+type OrderGrouped {
+  key:   OrderGroupKey!   # composite — every requested groupBy field present
+  count: Int!
+  sum:   OrderSumFields
+  # ... no recursive subgroups field — flat results
+}
+```
+
+## Features
+
+- **Hasura-canonical schema shape.** `<Model>Aggregate { count, countDistinct, sum, avg, min, max, stddev, variance, boolAnd, boolOr, arrayAgg, stringAgg }`.
+- **Odoo-grade group-by.** Multi-level via composite keys (flat result rows), dual date-granularity tracks (`date_trunc` returning `DateTime` AND `date_part::int` returning `Int`), timezone-correct bucketing.
+- **HAVING with aggregate aliases.** `{ countGt: 5, sumTotalGt: 1000 }` — typed inputs generated per measure.
+- **Ordering on aggregates.** `[{ field: "total:sum", direction: DESC }]` — fail-loud on unknown terms (Odoo's pre-17 silent-drop bug avoided).
+- **Standalone backend primitive.** `compute_aggregation(qs, group_by, aggregates, having, order_by, ...)` is callable from any Python context — DRF view, Celery task, admin script, MCP tool — not just GraphQL resolvers.
+- **Determinism.** Type generation produces byte-identical SDL for the same inputs.
+- **No magic.** Every operator, every granularity, every type is whitelisted.
+
+## Non-goals
+
+- **Cross-database aggregation.** PostgreSQL + SQLite only. SQLite degrades gracefully on `array_agg`/`string_agg`/`stddev`/`variance` — those operators raise `OperatorNotSupportedError` at resolver entry.
+- **Auto-traversal of one-to-many / many-to-many for measures.** This is the silent row-multiplication footgun [Odoo refuses to ship](https://github.com/odoo/odoo/blob/18.0/odoo/models.py); we follow. `array_agg` is the explicit escape hatch.
+- **Permission integration.** The library expects a pre-scoped queryset — the caller has already applied `accessible_by(user)` or equivalent. This keeps the library compatible with django-guardian, django-rules, [django-rebac](#) (when shipped), or hand-rolled permission systems.
+
+## Status
+
+Beta (v0.2.1). The schema shape, operator vocabulary, and `compute_aggregation` signature are stable for early adopters, but minor-level iteration is still expected before a 1.0 stability commitment — see [`docs/SPEC.md`](./docs/SPEC.md) § 16. Runtime: Python 3.13, Django 6.0.
+
+## Documentation
+
+- Full contract: [`docs/SPEC.md`](./docs/SPEC.md) — operator catalog, granularity tracks, HAVING semantics, ordering rules, timezone handling, and the Odoo-derived footgun audit.
+- Naming and wire vocabulary: [`docs/TERMINOLOGY.md`](./docs/TERMINOLOGY.md)
+- Contributor quality gate: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
+
+## License
+
+BSD-3-Clause.

strawberry_django_aggregates-0.2.1/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name            = "strawberry-django-aggregates"
+version         = "0.2.1"
+description     = "Hasura-shape aggregations over Django querysets in Strawberry GraphQL — count, sum, avg, min, max, stddev, variance, array_agg + Odoo-grade group-by with timezone-correct date bucketing."
+readme          = "README.md"
+requires-python = ">=3.14"
+license         = { text = "BSD-3-Clause" }
+authors         = [{ name = "strawberry-django-aggregates maintainers" }]
+keywords        = [
+  "django", "strawberry", "graphql", "aggregate", "groupby",
+  "hasura", "postgraphile", "odoo", "analytics",
+]
+classifiers     = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Django",
+  "Framework :: Django :: 6.0",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: BSD License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "django>=6.0",
+  "strawberry-graphql>=0.315.0",
+  "strawberry-graphql-django>=0.82.0",
+]
+
+[project.optional-dependencies]
+# Postgres-only operators (array_agg, string_agg, stddev, variance).
+# When this extra is NOT installed, those operators raise OperatorNotSupportedError
+# at resolver entry on non-Postgres connections.
+postgres = []
+
+[project.urls]
+Homepage      = "https://github.com/Apexive/strawberry-django-aggregates"
+Documentation = "https://github.com/Apexive/strawberry-django-aggregates/blob/main/docs/SPEC.md"
+Issues        = "https://github.com/Apexive/strawberry-django-aggregates/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-django>=4",
+  "ruff>=0.6",
+  "mypy>=1.10",
+  "django-stubs>=5",
+]
+
+[build-system]
+requires      = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where   = ["."]
+include = ["strawberry_django_aggregates*"]
+exclude = ["tests*", "docs*"]
+
+[tool.ruff]
+line-length    = 79
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+# Django is configured programmatically in tests/conftest.py.
+python_files = ["test_*.py"]
+testpaths    = ["tests"]
+addopts      = "-ra --strict-markers"
+pythonpath   = ["."]

strawberry_django_aggregates-0.2.1/setup.cfg

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

strawberry_django_aggregates-0.2.1/strawberry_django_aggregates/__init__.py

@@ -0,0 +1,146 @@
+"""strawberry-django-aggregates — Hasura aggregations for Django.
+
+Public surface:
+
+- :class:`AggregateBuilder` — convenience builder; emits all aggregate
+  types and the corresponding strawberry fields for a given model.
+- :func:`make_aggregate_type` — generate the ``<Model>Aggregate`` type.
+- :func:`make_grouped_type` — generate the ``<Model>Grouped`` /
+  ``<Model>GroupedResult`` types.
+- :func:`make_having_input` — generate the ``<Model>Having`` input.
+- :func:`make_group_by_spec` — generate the ``<Model>GroupBySpec`` input.
+- :func:`compute_aggregation` — backend primitive; returns flat
+  composite-key result rows. Callable outside GraphQL.
+- :class:`AggregateOp` — enum of aggregate operators.
+- :class:`TimeGranularity`, :class:`NumberGranularity` — enums of date
+  bucketing tokens (``date_trunc`` and ``date_part::int`` respectively).
+- :func:`parse_aggregate_order` — parser for ``"<field>:<op>"`` order
+  terms; raises on unknown.
+- :data:`BigInt` — string-encoded 64-bit signed integer scalar. Output
+  type for ``SUM`` over integer Django fields (Postgres widens to
+  ``bigint``; the 32-bit GraphQL ``Int`` would silently overflow).
+- :class:`BucketRange` + :func:`bucket_range` — half-open ``[from, to)``
+  interval emitted as a sibling on ``<Model>GroupKey`` for each
+  TIME-granularity bucket (SPEC § 7).
+- :func:`generate_bucket_spine` + :func:`fill_bucket_results` —
+  empty-bucket filling helpers powering ``compute_aggregation(fill=True)``
+  (SPEC § 7.2). Pure stdlib; callable from any Python context.
+- :func:`encode_group_cursor` + :func:`decode_group_cursor` — opaque
+  cursor encoding for Relay-style grouped pagination (SPEC § 4
+  cursor-pagination). Pure stdlib; the same encoding is used by the
+  builder's connection field.
+- :func:`register_relation_aggregate` — attach a
+  ``<relation>Aggregate(filter: ...)`` field on an existing
+  strawberry-django parent type so callers can issue
+  ``customer.ordersAggregate { count, sum { total } }``. Per-row
+  resolver in v1.0; dataloader-based batching is a v1.x improvement
+  (SPEC § 4.2 / Stream 9).
+- :func:`make_grouped_connection_type` — emit Relay-style
+  ``<Model>GroupedConnection`` / ``<Model>GroupedEdge`` types.
+- Errors: :class:`AggregateError`, :class:`OperatorNotSupportedError`,
+  :class:`OrderFieldNotAllowed`, :class:`AggregationAcrossRelationError`.
+
+See ``docs/SPEC.md`` for the full contract.
+"""
+
+from __future__ import annotations
+
+from strawberry_django_aggregates.builder import AggregateBuilder
+from strawberry_django_aggregates.compiler import (
+    bucket_range,
+    compute_aggregation,
+)
+from strawberry_django_aggregates.errors import (
+    AggregateError,
+    AggregationAcrossRelationError,
+    GranularityNotApplicable,
+    GroupByFieldNotAllowed,
+    HavingFieldNotAllowed,
+    JSONPathNotAllowed,
+    OperatorNotSupportedError,
+    OrderFieldNotAllowed,
+)
+from strawberry_django_aggregates.fill import (
+    fill_bucket_results,
+    generate_bucket_spine,
+)
+from strawberry_django_aggregates.granularity import (
+    NumberGranularity,
+    TimeGranularity,
+    validate_week_start,
+)
+from strawberry_django_aggregates.operators import (
+    AggregateOp,
+    default_operators_for,
+)
+from strawberry_django_aggregates.ordering import (
+    comodel_ordering_terms,
+    parse_aggregate_order,
+)
+from strawberry_django_aggregates.pagination import (
+    decode_group_cursor,
+    encode_group_cursor,
+)
+from strawberry_django_aggregates.relations import (
+    register_relation_aggregate,
+)
+from strawberry_django_aggregates.types import (
+    BigInt,
+    BucketRange,
+    make_aggregate_type,
+    make_group_by_spec,
+    make_grouped_connection_type,
+    make_grouped_type,
+    make_having_input,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Builder (high-level)
+    "AggregateBuilder",
+    # Type generators
+    "make_aggregate_type",
+    "make_grouped_type",
+    "make_grouped_connection_type",
+    "make_having_input",
+    "make_group_by_spec",
+    # Backend primitive
+    "compute_aggregation",
+    # Vocabularies
+    "AggregateOp",
+    "TimeGranularity",
+    "NumberGranularity",
+    "validate_week_start",
+    "default_operators_for",
+    # Custom scalars
+    "BigInt",
+    # Bucket range — half-open [from, to) interval for TIME-granularity
+    # group-by buckets (SPEC § 7 / Stream 5).
+    "BucketRange",
+    "bucket_range",
+    # Empty-bucket filling — dense bucket spine over date-bucketed
+    # results (SPEC § 7.2 / Stream 7).
+    "fill_bucket_results",
+    "generate_bucket_spine",
+    # Cursor pagination — opaque base64 / JSON encoding over the
+    # canonical-order group-by alias values (SPEC § 4 / Stream 11).
+    "encode_group_cursor",
+    "decode_group_cursor",
+    # Cross-relation aggregate field — attach
+    # ``<relation>Aggregate(filter: ...)`` to a strawberry-django
+    # parent type (SPEC § 4.2 / Stream 9).
+    "register_relation_aggregate",
+    # Ordering
+    "parse_aggregate_order",
+    "comodel_ordering_terms",
+    # Errors
+    "AggregateError",
+    "OperatorNotSupportedError",
+    "OrderFieldNotAllowed",
+    "AggregationAcrossRelationError",
+    "HavingFieldNotAllowed",
+    "GroupByFieldNotAllowed",
+    "GranularityNotApplicable",
+    "JSONPathNotAllowed",
+]