# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['garnett', 'garnett.templatetags']

package_data = \
{'': ['*'], 'garnett': ['templates/admin/*', 'templates/garnett/*']}

install_requires = \
['django>=3.1.0,<3.2.0', 'langcodes>=2.1,<2.2']

setup_kwargs = {
    'name': 'django-garnett',
    'version': '0.1.0',
    'description': 'Simple translatable Django fields',
    'long_description': '# django-garnett\n\nDjango Garnett is a field level translation library that allows you to store strings in multiple languages for fields in Django - with minimal changes to your models and without having to rewrite your code (mostly).\n\nIn summary it allows you to do this:\n\n<table>\n<tr>\n    <td>\n        <tt>models.py</tt>\n    <td>\n        You can do this!\n</tr>\n<tr>\n<td>\nBy changing your models from this...\n\n```python\nclass Greeting(models.model):\n    text = CharField(max_length=150)\n    target = models.CharField()\n    def __str__(self):\n        return f"{self.greeting}, {self.target}"\n\n```\n\nto this...\n\n```python\n# Import garnett\nfrom garnett.fields import Translated\n\nclass Greeting(models.model):\n    # Convert greeting to a translatable field\n    text = Translated(CharField(max_length=150))\n    target = models.CharField()\n    def __str__(self):\n        return f"{self.greeting} {self.target}"\n```\n</td>\n<td>\n\n```python\ngreeting = Greeting(text="Hello", target="World")\n\nwith set_field_language("en"):\n    greeting.text = "Hello"\nwith set_field_language("fr"):\n    greeting.text = "Bonjour"\n\ngreeting.save()\ngreeting.refresh_from_db()\n\nwith set_field_language("en"):\n    print(greeting.text)\n    print(greeting)\n# >>> "Hello"\n# >>> "Hello World"\n\nwith set_field_language("fr"):\n    print(greeting.text)\n    print(greeting)\n# >>> "Bonjour"\n# >>> "Bonjour World!"\n\nwith set_field_language("en"):\n    print(greeting.text)\n    print(greeting)\n# >>> "Hello"\n# >>> "Hello World"\n    Greeting.objects.filter(title="Hello").exists()\n# >>> True\n    Greeting.objects.filter(title="Bonjour").exists()\n# >>> False\n    Greeting.objects.filter(title__fr="Bonjour").exists()\n# >>> True!!\n\n# Assuming that GARNETT_DEFAULT_TRANSLATABLE_LANGUAGE="en"\n# Or a middleware has set the language context\nprint(greeting.text)\n# >>> Hello\nprint(greeting)\n# >>> Hello World!\n\n```\n\n</td>\n</table>\n\nTested on:\n\n  - Django 3.1+\n  - Postgres, SQLite, MariaDB\n  - Python 3.7+\n\n\nPros:\n* Fetching all translations for a models requires a single query\n* Translations are stored in a single database field with the model\n* Translations act like regular a field `Model.field_name = "some string"` and `print(Model.field_name)` work as you\'d expect\n* Includes a configurable middleware that can set the current language context based on users cookies, query string or HTTP headers\n* Works nicely with Django Rest Framework\n\nCons:\n* You need to alter the models, so you can\'t make third-party libraries translatable.\n\n## Why write a new Django field translator?\n\nA few reasons:\n* Most existing django field translation libraries are static, and add separate database columns per translation.\n* We needed a library that could be added in without requiring a rewrite of a large code base.\n\nNote: Field language is different to the django display language. Django can be set up to translate your pages based on the users browser and serve them with a user interface in their preferred language.\n\nGarnett *does not* use the browser language by design - a user with a French browser may want the user interface in French, but want to see content in English.\n\n\n# How to install\n\n1. Add `django-garnett` to your dependencies. eg. `pip install django-garnett`\n2. Convert your chosen field using the `Translated` function\n\n    * For example: `title = fields.Translated(models.CharField(*args))`\n\n3. Add `GARNETT_TRANSLATABLE_LANGUAGES` (a callable or list of [language codes][term-language-code]) to your django settings.\n    > Note: At the moment there is no way to allow "a user to enter any language".\n4. Add `GARNETT_DEFAULT_TRANSLATABLE_LANGUAGE` (a callable or single [language code][term-language-code]) to your settings.\n5. Re-run `django makemigrations` & `django migrate` for any apps you\'ve updated.\n6. Thats mostly it.\n\nYou can also add a few value adds:\n\n7. (Optional) Add a garnett middleware to take care of field language handling:\n\n    * You want to capture the garnett language in a context variable available in views use: `garnett.middleware.TranslationContextMiddleware`\n\n    * You want to capture the garnett language in a context variable available in views, and want to raise a 404 if the user requests an invalid language use: `garnett.middleware.TranslationContextNotFoundMiddleware`\n\n    * (Future addition) You want to capture the garnett language in a context variable available in views, and want to redirect to the default language if the user requests an invalid language use: `garnett.middleware.TranslationContextRedirectDefaultMiddleware`\n\n8. (Optional) Add the `garnett` app to your `INSTALLED_APPS` to use garnett\'s template_tags. If this is installed before `django.contrib.admin` it also include a language switcher in the Django Admin Site.\n\n9. (Optional) Add a template processor:\n\n    * Install `garnett.context_processors.languages` this will add `garnett_languages` (a list of available `Language`s) and `garnett_current_language` (the currently selected language).\n\n## `Language` vs language\n\nDjango Garnett uses the python `langcodes` to determine more information about the languages being used - including the full name and local name of the language being used. This is stored as a `Language` object.\n\n\n## Django Settings options:\n\n* `GARNETT_DEFAULT_TRANSLATABLE_LANGUAGE`\n    * Stores the default language to be used for reading and writing fields if no language is set in a context manager or by a request.\n    * By default it is \'en-AU\' the [language code][term-language-code] for \'Strayan, the native tongue of inhabitants of \'Straya (or more commonly known as Australia). \n    * Can also be callable that returns list of language codes\n    * default: `\'en-AU\'`\n* `GARNETT_TRANSLATABLE_LANGUAGES`:\n    * Stores a list of [language codes][term-language-code] that users can use to save against TranslatableFields.\n    * Can also be callable that returns default language code\n    * default `[GARNETT_DEFAULT_TRANSLATABLE_LANGUAGE]`\n* `GARNETT_REQUEST_LANGUAGE_SELECTORS`:\n    * A list of string modules that determines the order of options used to determine the language selected by the user. The first selector found is used for the language for the request, if none are found the DEFAULT_LANGUAGE is used. These can any of the following in any order:\n        * `garnett.selector.query`: Checks the `GARNETT_QUERY_PARAMETER_NAME` for a language to display\n        * `garnett.selector.cookie`: Checks for a cookie called `GARNETT_LANGUAGE_CODE` for a language to display.\n            Note: you cannot change this cookie name.\n        * `garnett.selector.header`: Checks for a HTTP Header called `X-Garnett-Language-Code` for a language to display.\n            Note: you cannot change this Header name.\n        * `garnett.selector.browser`: Uses Django\'s `get_language` to get the users browser/UI language as determined by Django.\n    * For example, if you only want to check headers and cookies in that order, set this to `[\'garnett.selector.header\', \'garnett.selector.cookie\']`.\n    * default: `[\'garnett.selector.query\', \'garnett.selector.cookie\', \'garnett.selector.header\']`\n* `GARNETT_QUERY_PARAMETER_NAME`:\n    * The query parameter used to determine the language requested by a user during a HTTP request.\n    * default: `glang`\n\nAdvanced Settings (you probably don\'t need to adjust these)\n* `GARNETT_TRANSLATABLE_FIELDS_PROPERTY_NAME`:\n    * Garnett adds a property to all models that returns a list of all TranslatableFields. By default, this is \'translatable_fields\', but you can customise it here if you want.\n    * default: `translatable_fields`\n* `GARNETT_TRANSLATIONS_PROPERTY_NAME`:\n    * Garnett adds a property to all models that returns a dictionary of all translations of all TranslatableFields. By default, this is \'translations\', but you can customise it here if you want.\n    * default: `translations`\n\n\n## Why call it Garnett?\n\n* Libraries need a good name.\n* Searching for "Famous Translators" will tell you about [Constnace Garnett](https://en.wikipedia.org/wiki/Constance_Garnett).\n* Searching for "Garnett Django" shows there was no library with this name. It did however talk about [Garnet Clark](https://en.wikipedia.org/wiki/Garnet_Clark) (also spelled Garnett), a jazz pianist who played with Django Reinhart - the namesake of the Django Web Framework.\n* Voila - a nice name\n\n## Warnings\n\n* `contains == icontains` For cross database compatibility reasons this library treats `contains` like `icontains`. I don\'t know why - https://www.youtube.com/watch?v=PgGNWRtceag\n* Due to how django sets admin form fields you will not get the admin specific widgets like\n  `AdminTextAreaWidget` on translated fields in the django admin site by default. They can however\n  be specified explicitly on the corresponding model form\n\nneed to run tests like this for now: PYTHONPATH=../ ./manage.py shell\n\n[term-language-code]: https://docs.djangoproject.com/en/3.1/topics/i18n/#term-language-code\n',
    'author': 'Aristotle Metadata Enterprises',
    'author_email': None,
    'maintainer': None,
    'maintainer_email': None,
    'url': None,
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'python_requires': '>=3.7,<4.0',
}


setup(**setup_kwargs)
