Metadata-Version: 2.1
Name: django-attachments
Version: 1.8
Summary: django-attachments is generic Django application to attach Files (Attachments) to any model.
Home-page: https://github.com/bartTC/django-attachments
Author: Martin Mahner
Author-email: martin@mahner.org
License: MIT
Description: .. image:: https://badge.fury.io/py/django-attachments.svg
            :target: https://badge.fury.io/py/django-attachments
        
        .. image:: https://travis-ci.org/bartTC/django-attachments.svg?branch=master
            :target: https://travis-ci.org/bartTC/django-attachments
        
        .. image:: https://api.codacy.com/project/badge/Grade/e13db6df2a2148b08c662798642aa611
            :alt: Codacy Badge
            :target: https://app.codacy.com/app/bartTC/django-attachments
        
        .. image:: https://api.codacy.com/project/badge/Coverage/e13db6df2a2148b08c662798642aa611
            :target: https://www.codacy.com/app/bartTC/django-attachments
        
        ==================
        django-attachments
        ==================
        
        django-attachments is a generic set of template tags to attach any kind of
        files to models.
        
        Installation:
        =============
        
        1. Put ``attachments`` to your ``INSTALLED_APPS`` in your ``settings.py``
           within your django project::
        
            INSTALLED_APPS = (
                ...
                'attachments',
            )
        
        2. Add the attachments urlpattern to your ``urls.py``::
        
            url(r'^attachments/', include('attachments.urls', namespace='attachments')),
        
        3. Migrate your database::
        
            ./manage.py migrate
        
        4. Grant the user some permissions:
        
           * For **adding attachments** grant the user (or group) the permission
             ``attachments.add_attachment``.
        
           * For **deleting attachments** grant the user (or group) the permission
             ``attachments.delete_attachment``. This allows the user to delete their
             attachments only.
        
           * For **deleting foreign attachments** (attachments by other users) grant
             the user the permission ``attachments.delete_foreign_attachments``.
        
        5. Set ``DELETE_ATTACHMENTS_FROM_DISK`` to ``True`` if you want to remove
           files from disk when Attachment objects are removed!
        
        6. Configure ``FILE_UPLOAD_MAX_SIZE`` (optional). This is the maximum size in
           bytes before raising form validation errors. If not set there is no restriction
           on file size.
        
        Mind that you serve files!
        ==========================
        
        django-attachments stores the files in your site_media directory and does not modify
        them. For example, if an user uploads a .html file your webserver will probably display
        it in HTML. It's a good idea to serve such files as plain text. In a Apache2
        configuration this would look like::
        
            <Location /site_media/attachments>
                AddType text/plain .html .htm .shtml .php .php5 .php4 .pl .cgi
            </Location>
        
        
        House-keeping
        =============
        
        django-attachments provides the ``delete_stale_sttachments`` management command.
        It will remove all attachments for which the related objects don't exist anymore!
        Sys-admins could then::
        
            ./manage.py delete_stale_attachments
        
        You may also want to execute this via cron.
        
        
        Tests
        =====
        
        Run the testsuite in your local environment using ``pipenv``::
        
            $ cd django-attachments/
            $ pipenv install --dev
            $ pipenv run pytest attachments/
        
        Or use tox to test against various Django and Python versions::
        
            $ tox -r
        
        You can also invoke the test suite or other 'manage.py' commands by calling
        the ``django-admin`` tool with the test app settings::
        
            $ cd django-attachments/
            $ pipenv install --dev
            $ pipenv run test
            $ pipenv run django-admin.py runserver
        
        Usage:
        ======
        
        In contrib.admin:
        -----------------
        
        django-attachments provides a inline object to add a list of attachments to
        any kind of model in your admin app.
        
        Simply add ``AttachmentInlines`` to the admin options of your model. Example::
        
            from django.contrib import admin
            from attachments.admin import AttachmentInlines
        
            class MyEntryOptions(admin.ModelAdmin):
                inlines = (AttachmentInlines,)
        
        .. image:: http://cloud.github.com/downloads/bartTC/django-attachments/attachments_screenshot_admin.png
        
        In your frontend templates:
        ---------------------------
        
        First of all, load the attachments_tags in every template you want to use it::
        
            {% load attachments_tags %}
        
        django-attachments comes with some templatetags to add or delete attachments
        for your model objects in your frontend.
        
        1. ``get_attachments_for [object]``: Fetches the attachments for the given
           model instance. You can optionally define a variable name in which the attachment
           list is stored in the template context (this is required in Django 1.8). If
           you do not define a variable name, the result is printed instead.
        
           {% get_attachments_for entry as "attachments_list" %}
        
        2. ``attachments_count [object]``: Counts the attachments for the given
           model instance and returns an int::
        
           {% attachments_count entry %}
        
        3. ``attachment_form``: Renders a upload form to add attachments for the given
           model instance. Example::
        
            {% attachment_form [object] %}
        
           It returns an empty string if the current user is not logged in.
        
        4. ``attachment_delete_link``: Renders a link to the delete view for the given
           *attachment*. Example::
        
            {% for att in attachments_list %}
                {{ att }} {% attachment_delete_link att %}
            {% endfor %}
        
           This tag automatically checks for permission. It returns only a html link if the
           give n attachment's creator is the current logged in user or the user has the
           ``delete_foreign_attachments`` permission.
        
        Quick Example:
        ==============
        
        ::
        
            {% load attachments_tags %}
            {% get_attachments_for entry as my_entry_attachments %}
        
            <span>Object has {% attachments_count entry %} attachments</span>
            {% if my_entry_attachments %}
            <ul>
            {% for attachment in my_entry_attachments %}
                <li>
                    <a href="{{ attachment.attachment_file.url }}">{{ attachment.filename }}</a>
                    {% attachment_delete_link attachment %}
                </li>
            {% endfor %}
            </ul>
            {% endif %}
        
            {% attachment_form entry %}
        
            {% if messages %}
            <ul class="messages">
            {% for message in messages %}
                <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>
                    {{ message }}
                </li>
            {% endfor %}
            </ul>
            {% endif %}
        
        Changelog:
        ==========
        
        v1.8 (2020-09-03)
        -----------------
        
        - Alter ``object_id`` from ``TextField()`` to ``CharField(max_length=64)``,
          and keep the db_index argument. This resolves the issues on MariaDB/MySQL.
        
        
        v1.7 (2020-08-31) - **broken on MariaDB/MySQL**
        -----------------------------------------------
        
        - Add DB index to ``object_id``, ``created`` and ``modified`` fields.
        - Add ``delete_stale_attachments`` command to remove attachments for which
          the corresponding object has been deleted.
        - Add ``Attachment.attach_to()`` method for moving attachments between
          different objects.
        - Django 3.1 compatibility and tests.
        
        
        v1.6 (2020-08-17)
        -----------------
        
        - Primary keys of related objects other than Integers (such as UUIDs)
          are now supported.
        
        v1.5 (2019-12-08)
        -----------------
        
        - Dropped support for Python 3.4.
        - Added suport for Python 3.8.
        - Django 3.0 compatibility and tests.
        - Django 2.2 compatibility and tests.
        
        v1.4.1 (2019-07-22)
        -------------------
        
        - The templatetags now allow an optional `next` parameter.
        
        v1.4 (2019-02-14)
        -----------------
        
        - Dropped Support for Django <=1.10.
        - Fixed 'next' URL argument redirect.
        
        v1.3.1 (2019-01-24):
        --------------------
        
        - Django 2.1 and Python 3.7 support.
        - General code cleanup.
        
        v1.3 (2018-01-09):
        ------------------
        
        - Added a missing database migration.
        - New templatetag ``attachments_count``.
        - New setting ``DELETE_ATTACHMENTS_FROM_DISK`` to delete attachment files
          if the attachment model is deleted.
        - New setting ``FILE_UPLOAD_MAX_SIZE`` to deny file uploads exceeding this
          value.
        
        v1.2 (2017-12-15):
        ------------------
        
        - Django 1.11 and 2.0 compatibility and tests.
        
        v1.1 (2017-03-18):
        ------------------
        
        - Django 1.10 compatibility and tests.
        - Python 3.6 compatibility and tests.
        - Fixes problems where models have a foreign key named something other
          than "id".
        
        v1.0.1 (2016-06-12):
        --------------------
        
        - Added finnish translation.
        - Minor test suite improvements.
        
        v1.0 (2016-03-19):
        ------------------
        
        - General code cleanup to keep compatibility with the latest Django
          (currently 1.8 upwards) as well as Python3. Introduced full testsuite.
        
        - *Backwards incompatible*: The attachment views now use a urlpattern
          ``namespace`` so you need to adjust the urlpattern::
        
            url(r'^attachments/', include('attachments.urls', namespace='attachments')),
        
        - *Backwards incompatible*: The quotes around the ``as`` variable name
           must be removed::
        
             {% get_attachments_for entry as "my_entry_attachments" %}
        
             becomes
        
             {% get_attachments_for entry as my_entry_attachments %}
        
        - *Possibly backwards incompatible*: The old version had bugs around
           permissions and were not enforcing it in all places. From now on the
           related permissions ``add_attachment`` and ``delete_attachment`` must
           been applied to all related users.
        
        v0.3.1 (2009-07-29):
        --------------------
        
        - Added a note to the README that you should secure your static files.
        
        v0.3 (2009-07-22):
        ------------------
        
        - This version adds more granular control about user permissons. You need
          to explicitly add permissions to users who should been able to upload,
          delete or delete foreign attachments.
        
          This might be *backwards incompatible* as you did not need to assign
          add/delete permissions before!
        
Keywords: django,attachments,files,upload
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Framework :: Django
Provides-Extra: test
