{"id":50730892,"url":"https://github.com/hapytex/django-fdict","last_synced_at":"2026-06-10T08:31:53.385Z","repository":{"id":349168649,"uuid":"1201057167","full_name":"hapytex/django-fdict","owner":"hapytex","description":"Dictionary mappings in the database.","archived":false,"fork":false,"pushed_at":"2026-04-04T15:05:43.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-04T16:51:18.917Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hapytex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":"https://www.buymeacoffee.com/hapytex"}},"created_at":"2026-04-04T06:35:32.000Z","updated_at":"2026-04-04T15:05:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hapytex/django-fdict","commit_stats":null,"previous_names":["hapytex/django-fdict"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hapytex/django-fdict","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapytex%2Fdjango-fdict","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapytex%2Fdjango-fdict/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapytex%2Fdjango-fdict/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapytex%2Fdjango-fdict/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hapytex","download_url":"https://codeload.github.com/hapytex/django-fdict/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapytex%2Fdjango-fdict/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34144679,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T08:31:53.266Z","updated_at":"2026-06-10T08:31:53.380Z","avatar_url":"https://github.com/hapytex.png","language":"Python","funding_links":["https://www.buymeacoffee.com/hapytex"],"categories":[],"sub_categories":[],"readme":"# `django-fdict`\n\n\u003e *Dictionary mappings in the database.*\n\n# Introduction\n\nIn databases, one typically uses `JOIN`s to perform mappings. Imagine for example we have a database of products, then we can add the vat regime, and make a JOIN:\n\n```python\nfrom django.db import models\n\nclass VATRate(models.Model):\n    name = models.CharField(max_length=32, unique=True)\n    pct = models.FloatField()\n\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    vat_rate = models.ForeignKey(VATRate, on_delete=models.PROTECT)\n```\n\nand then we can annotate by using a JOIN, like:\n\n```python\nProduct.objects.annotate(vat_pct=F('vate_rate__pct'))\n```\n\nor we can load the entire `VATRate` object along each product with `.select_related(..)`:\n\n```python\nProduct.objects.select_related('vate_rate')\n```\n\nand then fetch it through `.vat_rate`.\n\n---\n\nOccasionally, we might want to perform mappings with a Python dictionary. This might be the case when we have no control over the database tables, and the vat rate is missing.\n\nIf for example the `Product` contains a `CharField` with the vat rate:\n\n```python\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    country = models.CharField(max_length=2)\n    country_of_origin = models.CharField(max_length=2)\n    vat_rate = models.CharField(max_length=32)\n```\n\nWe might want to perform a dictionary mapping with:\n\n```python\n# will *not* work\n\nvat_rates = {'R03': 0.21, 'R02': 0.12, 'R01': 0.06}\n\nProduct.annotate(vat_pct=vat_rates[F('vat_rate')])\n```\n\nThis is the problem `django-fdict` wants to solve. We first wrap the entries in an `FDict`, which is a subclass of `dict`:\n\n```python\n# *hopefully* works\n\nfrom django_fdict import FDict\n\nvat_rates = FDict({'R03': 0.21, 'R02': 0.12, 'R01': 0.06})\n\nProduct.annotate(vat_pct=vat_rates[F('vat_rate')])\n```\n\nthis will then set an attribute `vat_pct` to the \n\nUsually mapping just to get an attribute is *not* a good idea. It is mainly done for further filtering *in* the queryset, like:\n\n```python\n# *hopefully* works\n\nfrom django_fdict import FDict\n\nvat_rates = FDict({'R03': 0.21, 'R02': 0.12, 'R01': 0.06})\n\nProduct.annotate(vat_pct=vat_rates[F('vat_rate')]).filter(vat_pct__range=(0.10, 0.15))\n```\n\n# Multiple fields\n\nOne can also apply the trick with two or more fields. Then `FDict` is given a dictionary where the keys are tuples, for example:\n\n```python\n# *hopefully* works\n\nfrom django_fdict import FDict\n\nvat_rates = FDict({('R03', 'BE'): 0.21, ('R02', 'BE'): 0.12, ('R01', 'BE'): 0.06, ('R03', 'FR'): 0.2, ('R02', 'FR'): 0.1})\n\nProduct.annotate(vat_pct=vat_rates[F('vat_rate'), F('country')]).filter(vat_pct__range=(0.10, 0.15))\n```\n\nwhich normally fetches the VAT rates based on the vat rate label, and the country code.\n\nOne can also pass non-`F` values in the lookups, then it will first filter down the dictionary:\n\n```python\n# *hopefully* works\n\nfrom django_fdict import FDict\n\nvat_rates = FDict({('R03', 'BE'): 0.21, ('R02', 'BE'): 0.12, ('R01', 'BE'): 0.06, ('R03', 'FR'): 0.2, ('R02', 'FR'): 0.1})\n\nProduct.annotate(vat_pct=vat_rates[F('vat_rate'), 'BE']).filter(vat_pct__range=(0.10, 0.15))\n```\n\nnow we thus always use `BE` (Belgium) as country in the dictionary lookups.\n\n# Query-like keys/values\n\nStrictly speaking the keys, and the values in the dictionary can also be database expressions, for example with the given model:\n\n```python\n# *hopefully* works\n\nfrom django_fdict import FDict\n\norigin = F('country_of_origin')\n\nvat_rates = FDict({('R03', origin): 0.21, ('R02', origin): 0.12, ('R01', origin): 0.06})\n\nProduct.annotate(vat_pct=vat_rates[F('vat_rate'), F('country')])\n```\n\nit will produce `NULL` if the `country_of_origin` is not the same as the `country` field. But this makes mapping more complicated and eventually the order in which the entries are mapped might determine the outcome.\n\n# Technical details\n\nDatabases allow to work with `CASE … WHEN … THEN … ELSE … END`. The `FDict` converts the dictionary into a (long) chain of `WHEN` expressions.\n\nSo for the first example we use:\n\n```sql\nSELECT *\n       CASE\n           WHEN vat_label = 'R03' THEN 0.21\n           WHEN vat_label = 'R02' THEN 0.12\n           WHEN vat_label = 'R01' THEN 0.06\n           ELSE NULL\n        END as vat_pct\nFROM product\n```\n\nthis can also work for more complicated conditions, like:\n\n```sql\nSELECT *\n       CASE\n           WHEN vat_label = 'R03' AND country='BE' THEN 0.21\n           WHEN vat_label = 'R02' AND country='BE' THEN 0.12\n           WHEN vat_label = 'R01' AND country='BE' THEN 0.06\n           WHEN vat_label = 'R03' AND country='FR' THEN 0.20\n           WHEN vat_label = 'R02' AND country='FR' THEN 0.10\n           ELSE NULL\n        END as vat_pct\nFROM product\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapytex%2Fdjango-fdict","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhapytex%2Fdjango-fdict","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapytex%2Fdjango-fdict/lists"}