Merge pull request #145 from druids/UpdatedDocs

Updated documentation

docs/installation.rst

@@ -6,24 +6,23 @@ Installation
 Python/Django versions
 ----------------------
 
-+----------------------+------------+
-|  Python              | Django     |
-+======================+============+
-| 2.7, 3.4, 3.5, 3.6   | 1.7 - 1.10 |
-+----------------------+------------+
++----------------------------+------------------+
+|  Python                    | Django           |
++============================+==================+
+| 3.5, 3.6, 3.9, 3.10, 3.11  | >=2.2 <4         |
++----------------------------+------------------+
 
 
 Requirements
 ------------
 
  * **django** -- Chamber extends Django, therefore it is a natural dependency
  * **pyprind** -- used in CSV importers to show progress bars
- * **six** -- to provide Python 2/3 compatibility
- * **filemagic**
- * **unidecode**
+ * **filemagic** -- to check type of the files from its content
+ * **unidecode** -- to convert unicode characters to ascii
 
 
-Using Pip
+Using pip
 ---------
 Django-chamber is not currently inside *PyPI* but in the future you will be able to use:
 

docs/models.rst

@@ -68,9 +68,6 @@ The ``django.db.models.FileField`` with ``RestrictedFileFieldMixin`` options.
 
 ``chamber.models.fields.PriceField`` with a default ``django.core.validators.MinValueValidator`` set to ``0.00``.
 
-.. class:: chamber.models.fields.SouthMixin
-
-Mixin for automatic South migration of custom model fields.
 
 SmartModel
 ----------
@@ -149,6 +146,24 @@ SmartModel
 
         Update instance field values with values sent in ``changed_fields`` and finally instance is saved. If you want to update only changed fields in the database you can use parameter ``update_only_changed_fields`` to achieve it
 
+    .. method:: full_clean(exclude=None, *args, **kwargs)
+
+        The original django full_clean method is improved with calling extra clean_{field} methods on the model (it is similar to django forms clean methods::
+
+            class CustomModel(SmartModel):
+
+                name = models.CharField(max_length=100)
+
+                def clean_name(self):
+                    if len(self.name) >= 10:
+                        raise ValidationError('name must be lower than 10')
+
+        The method ``clean_name`` will be automatically called when the ``full_clean`` method is triggered and ValidationError will be added to the field error.
+
+    .. method:: get_locked_instance()
+
+        The method returns the new instance of the self object which is locked in the database with ``select_for_update``. Method must be used in the django atomic block.
+
 
 SmartMeta
 ---------

docs/transactions.rst

@@ -2,38 +2,42 @@ Transaction helpers
 ===================
 
 
-``chamber.utils.transaction.atomic``
+``chamber.utils.transaction``
 ------------------------------------
 
 .. function:: smart_atomic(using=None, savepoint=True, ignore_errors=None, reversion=True)
 
-        Like django ``transaction.smart_atomic()`` decorator chamber atomic can be used for surrounding method, function or block of code with db atomic block. But because we often uses reversion the atomic is surrounded with ``create_revision`` decorator. Reversion can be turned off with ``reversion`` argument
+    Like django ``transaction.smart_atomic()`` decorator chamber atomic can be used for surrounding method, function or block of code with db atomic block. But because we often uses reversion the atomic is surrounded with ``create_revision`` decorator. Reversion can be turned off with ``reversion`` argument.
 
 .. function:: pre_commit(callable, using=None)
 
-        Similar to django ``on_commit`` helper, but callable function is called before the data is saved to the database. Of no atomic bloc is activated callable is called imediatelly
+    Similar to django ``on_commit`` helper, but callable function is called just before the data is committed to the database. If no atomic block is activated callable is called immediately.
+
+.. function:: in_atomic_block(callable, using=None)
+
+    The function checks if your code is in the atomic block.
 
 
 ``chamber.utils.transaction.UniquePreCommitCallable``
 -----------------------------------------------------
 
 One time callable is registered and called only once. But all input parameters are stored inside list of kwargs.
 
-.. class:: chamber.utils.transaction.OneTimePreCommitHandler
+.. class:: chamber.utils.transaction.UniquePreCommitCallable
 
     .. method:: handle()
 
-        There should be implemented code that will be invoked after success pass though the code. Difference from ``PreCommitHandler.handle`` is that kwargs is stored inside list in the order how handlers was created
+        There should be implemented code that will be invoked after success pass though the code.
 
     .. method:: _get_unique_id()
 
         The uniqueness of the handler must be somehow defined. You must implement this method to define unique identifier of the handler. By default it is identified with has of the class
 
 
-``chamber.utils.transaction.InstanceOneTimePreCommitHandler``
+``chamber.models.handlers.InstanceOneTimePreCommitHandler``
 -------------------------------------------------------------
 
-Special type of unique handler that is identified with iteslf and model instance of the input model object.
+Special type of unique handler that is identified with itself and model instance of the input model object.
 
 .. class:: chamber.utils.transaction.InstanceOneTimePreCommitHandler
 

docs/utils.rst

@@ -184,3 +184,71 @@ is equivalent to
     def absolute_amount(self):
         return abs(self.amount)
     absolute_amount.short_description = 'amount'
+
+Tqdm
+----
+
+.. class:: chamber.utils.tqdm.tqdm
+
+The class extends ``tqdm`` library (https://tqdm.github.io/). Now the ``tqdm`` context processor can be used with th django commands. Django command stdout writes newline after every write to the stdout which breaks the progress bar::
+
+    # a custom command
+    from django.core.management.base import BaseCommand
+    from chamber.utils.tqdm import tqdm
+
+    class Command(BaseCommand):
+
+        def handle(self, *args, **options):
+            for i in tqdm(range(10), file=self.stdout):
+                custom_operation(i)
+
+
+Logging
+-------
+
+.. class:: chamber.logging.AppendExtraJSONHandler
+
+Log handler which writes every extra argument in the log to the output message in a json format::
+
+    # logged message with handler
+    logger.log('message', extra={'extra': 'data'})
+
+    # logger output
+    message --- {"extra": "data"}
+
+
+Storages
+--------
+
+.. class:: chamber.storages.BaseS3Storage
+
+Class fixes bugs in the boto3 library storage. For example you can write only bytes with the standard boto3 S3Boto3Storage. Strings will raise exception. The chamber BaseS3Storage adds possibility to saves strings to the storage.
+
+.. class:: chamber.storages.BasePrivateS3Storage
+
+Improves boto3 storage with url method. With this method you can generate temporary URL address to the private s3 storage. The URL will expire after ``CHAMBER_PRIVATE_S3_STORAGE_URL_EXPIRATION`` (default value is one day).
+
+Commands
+--------
+
+makemessages
+^^^^^^^^^^^^
+
+Django makemessages commands is expanded with another keywords which represents transaction strings. This keyword you can use instead of long django functions:
+
+* ``_l`` - instead of ``gettext_lazy``
+* ``_n`` - instead of ``ngettext``
+* ``_nl`` - instead of ``ngettext_lazy``
+* ``_p`` - instead of ``pgettext``
+* ``_np`` - instead of ``npgettext``
+* ``_pl`` - instead of ``pgettext_lazy``
+* ``_npl`` - instead of ``npgettext_lazy``
+
+Second improvement is parameter ``no-creation-date`` which remove ``POT-Creation-Date`` from the result file.
+
+initdata
+^^^^^^^^
+
+Init data is command similar to django ``loaddata``. The command automatically loads the file from the path defined in setting ``CHAMBER_INITAL_DATA_PATH``.
+
+