Metadata-Version: 2.1
Name: paperclip
Version: 2.7.0
Summary: Attach files to Django models
Home-page: https://github.com/makinacorpus/django-paperclip
Author: Makina Corpus
Author-email: geobi@makina-corpus.com
License: LPGL, see LICENSE file.
Download-URL: https://pypi.python.org/pypi/paperclip/
Platform: UNKNOWN
Classifier: Topic :: Utilities
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Requires-Python: >=3.6
Provides-Extra: dev
License-File: LICENSE

Paperclip
=========

Add attachments to Django models, used in `MapEntity <https://github.com/makinacorpus/django-mapentity>`_.


|release-status| |master-status| |master-coverage|

|python-versions| |django-versions|


.. |release-status| image:: https://img.shields.io/pypi/v/paperclip.svg
    :target: https://pypi.python.org/pypi/paperclip

.. |master-status| image:: https://github.com/makinacorpus/django-paperclip/actions/workflows/python-package.yml/badge.svg

.. |master-coverage| image:: https://codecov.io/gh/makinacorpus/django-paperclip/branch/master/graph/badge.svg?token=OB6f944vAt
    :target: https://codecov.io/gh/makinacorpus/django-paperclip

.. |python-versions| image:: https://img.shields.io/badge/python-%3E%3D%203.6-blue.svg

.. |django-versions| image:: https://img.shields.io/badge/django-%3E%3D%202.2-blue.svg


=======
INSTALL
=======

Installing from pypi (using pip)

::

    pip install paperclip


Installing from github

::

    pip install -e git://github.com/makinacorpus/django-paperclip.git#egg=django-paperclip


=======
UPGRADE
=======

After upgrade to 0.4.0, if you want to enable links to Youtube/Soundcloud media,
you have to add an additional column to the database:


.. code-block:: postgresql

    ALTER TABLE paperclip_attachment ADD COLUMN attachment_video VARCHAR(200) NOT NULL DEFAULT '';


===========
BASIC USAGE
===========

* Add ``easy_thumbnails``, ``embed_video`` and ``paperclip`` to ``INSTALLED_APPS``

* Include urls

::

    urlpatterns = [
        ...
        url(r'^paperclip/', include('paperclip.urls')),
        ...
    ]

* Include scripts in template

::

    <script src="{% static "paperclip/bootstrap-confirm.js" %}" type="text/javascript"></script>
    <script src="{% static "paperclip/spin.min.js" %}" type="text/javascript"></script>
    <script src="{% static "paperclip/paperclip.js" %}" type="text/javascript"></script>

If you use bootstrap 3 or bootstrap 4, please include ``paperclip/bootstrap-3-confirm.js`` or ``paperclip/bootstrap-4-confirm.js`` instead of ``paperclip/bootstrap-confirm.js``.

* Include list and form in template

::

    {% include 'paperclip/attachment_list.html' with object=my_instance attachment_form_next=my_instance.get_detail_url %}

* Add paperclip models in one of your apps

::

    class FileType(paperclip.models.FileType):
        pass

    class Attachment(paperclip.models.Attachment):
        pass

* Configure

Define the following django setting:

::

    PAPERCLIP_ENABLE_VIDEO = False,
    PAPERCLIP_FILETYPE_MODEL = 'myapp.FileType'
    PAPERCLIP_LICENSE_MODEL = 'myapp.License'
    PAPERCLIP_ATTACHMENT_MODEL = 'myapp.Attachment'
    PAPERCLIP_ACTION_HISTORY_ENABLED = True

* Make migration and migrate


=========
TEMPLATES
=========

Three templates are embeded and can easily be overriden :

* ``paperclip/attachment_list.html`` : renders a table displaying attached files for an object and an upload form using the two following templates
* ``paperclip/_attachment_table.html`` : renders a table displaying attached files for an object. You can add extra columns using ``block extra_column_header`` and ``block extra_column_data``
* ``paperclip/_attachment_form.html`` : renders an upload form




============
TEMPLATETAGS
============

Two templatetags are provided :

get_attachments_for
````````````````````
Resolves attachments that are attached to a given object. You can specify the variable name in the context the attachments are stored using the `as` argument. Default context variable name is `attachments`. You can filter on a specified FileType with the optional `only_type` argument.

Examples

::

    {% get_attachments_for my_instance as "my_attachments" %}
    {% get_attachments_for my_instance as "my_attachments" only_type my_filetype_instance %}

attachment_form
```````````````
Renders a "upload attachment" form. `obj` argument is required and represents the instance to which you want to associate the file. A bound form can be given optionnaly with the argument ``form``. Important : a ``attachment_form_next`` variable is expected in context. If you want to use a custom form class, you can add ``attachment_form_class`` variable in context too

Examples

::

    {% with object=my_instance attachment_form_next=my_instance.get_detail_url %}
        {% attachment_form object %}
    {% endwith %}

    OR

    # views.py
    ...
    context['object'] = my_instance
    context['attachment_form_next'] = my_instance.get_detail_url(=)
    context['attachment_form_class'] = MyAttachmentForm
    ...

    # template
    {% attachment_form object %}

==================
USE A CUSTOM FORM
==================

You can use a custom django form by following this steps. Parenthetically, It's the recommended solution if you want to use django-crispy-forms or django-floppyforms.

* Write your custom form :

::

    from paperclip.forms import AttachmentForm

    class MyAttachmentForm(AttachmentForm):
        ...

Note: To be sure to not break the form logic, we recommend to inherit from the native ``paperclip.forms.AttachmentForm``.

* Add your form class in a ``attachment_form_class`` variable of the main view context

::

    context['attachment_form_class'] = MyAttachmentForm

* Override ``'add_attachment'`` and ``'update_attachment'`` URLs to provide your custom form class in arguments

.. code-block:: python

    from my_app.forms import MyAttachmentForm

    urlpatterns = [
        path('paperclip/', include('paperclip.urls')),
        ...
        path('add-for/<str:app_label>/<str:model_name>/<int:pk>/',
            'paperclip.views.add_attachment',
            kwargs={'attachment_form': MyAttachmentForm},
            name="add_attachment"),

        path('update/<int:attachment_pk>/',
            'paperclip.views.update_attachment',
            kwargs={'attachment_form': MyAttachmentForm},
            name="update_attachment"),
        ...
    ]


Note: Be sure to write these URLs after having included paperclip URLs.

=======
CLEANUP
=======

Deleting or changing an attachment does not remove the old attached file from disk.
From time to time you can clean obsolete files by running:

::

    ./manage.py clean_attachments


=======
AUTHORS
=======

|makinacom|_

.. |makinacom| image:: https://github.com/makinacorpus.png
.. _makinacom:  https://www.makina-corpus.com


=======
LICENSE
=======

    * LGPL


=========
CHANGELOG
=========

2.7.0  (2023-02-15)
=======================

* Add safety checks on uploaded files
* Fix link to the project on Pypi when clicking the pypi badge (another pypi project is named `django-paperclip`)
* Fix typo in test-supporting HTML files (nothing was broken though)


2.6.1      (2022-07-07)
=======================

* Change setting names : `PAPERCLIP_MIN_ATTACHMENT_HEIGHT`, `PAPERCLIP_MIN_ATTACHMENT_WIDTH` => `PAPERCLIP_MIN_IMAGE_UPLOAD_WIDTH`, `PAPERCLIP_MIN_IMAGE_UPLOAD_HEIGHT`
* Fix check size of image only when it's an image


2.6.0      (2022-07-06)
=======================

** New **

* Add `PAPERCLIP_MAX_BYTES_SIZE_IMAGE` max size image form
* Add `PAPERCLIP_MIN_ATTACHMENT_HEIGHT` min height image form
* Add `PAPERCLIP_MIN_ATTACHMENT_WIDTH` min width image form


2.5.1      (2022-07-05)
=======================

* Add blocks templates


2.5.0      (2022-04-26)
=======================

** New **

* Add field license on attachment


2.4.3      (2022-04-08)
=======================

* Replace french column name to english column name


2.4.2      (2022-03-29)
=======================

** Fixes **

* Fix js init mode embed type should be File and not Youtube


2.4.1      (2022-03-18)
=======================

** Fixes **

* Fix form enable_link javascript


2.4.0      (2022-01-10)
=======================

** New **

* Support Django 4.0


2.3.4 (2021-12-13)
=======================

**New features**

- Add PAPERCLIP_RESIZE_ATTACHMENTS_ON_UPLOAD setting to enable resize attachments on upload
- Add PAPERCLIP_MAX_ATTACHMENT_WIDTH and PAPERCLIP_MAX_ATTACHMENT_HEIGHT to configure attachment resizing (defaults 1280px)
 

2.3.3      (2021-09-03)
=======================

** New **

* Display custom columns in attachment list

2.3.2 (2021-06-09)
==================

* Add a bootstrap-4-confirm


2.3.1 (2021-06-03)
==================

** New **

* Support django 3.2 and python 3.9
* Drop support Python 3.5


2.2.6 (2020-11-24)
==================

** New **

* Support for django 3.1


2.2.5 (2020-05-15)
==================

** New **

* Support for django 2.2 and 3.0
* Drop Django 1.11, 2.0, 2.1 and python 2 support
* Set automatic is_image db column

2.2.4 (2020-03-10)
==================

** Fixes **

* Show attachment file, video or link widget as required


2.2.3 (2019-12-31)
==================

** Fixes **

* Fix requirements for Django 2


2.2.2 (2019-10-08)
==================

** Fixes **

* Do not set author to current username by default
* Fix mode preselection


2.2.1 (2019-01-07)
==================

** Fixes **

* Fix permissions change, delete and delete_others


2.2.0 (2018-11-07)
==================

** New **

* Support Python3, Django 2.0 and 2.1
* Drop Django 1.8, 1.9 and 1.10 support


2.1.2 (2018-03-25)
==================

** New **

* Support Django 1.8 to 1.11


2.1.1 (2017-03-23)
==================

** Fixes **

* Fix releases required includes


2.1.0 (2017-03-23)
==================

** New **

* From now, Attachment model support external picture URLs


2.0.0 (2017-02-21)
==================

** BREAKING CHANGES **

* Provide an abstract model. Users are required to define their own
  Attachment model


1.0.0 (2017-01-14)
==================

** BREAKING CHANGES **

* Remove support of Django <= 1.7
* Rename parameter 'module_name' as 'model_name' in urls

** New **

* Support Django 1.8
* Add initial migration (Caution! it depends on app settings)


0.5.0 (2016-01-11)
==================

** New **

* Add a command to clean obsolete files


0.4.1 (2015-03-20)
==================

** Fixes **

* Fix uploaded file modification


0.4.0 (2015-03-20)
==================

** New **

* Allow to add links to Youtube or Soundcloud media


0.3.0 (2015-03-18)
==================

** Removed (WARNING: backward incompatibility) **

* Totally remove crispy_forms and floppy_forms integration (you can now override the form by a custom one instead)

** New **

* Allow usage of a custom form


0.2.3 (2014-12-15)
==================

* Handle swappable User model
* Embed spinner, bootstrap-confirm and add a bootstrap-3-confirm
* Remove crispy_forms dependency


0.2.2 (2014-11-14)
==================

* Fix permission check for attachments


0.2.0 (2014-11-12)
==================

* Allow to override file types from request.


0.1.3 (2014-11-07)
==================

* Fix packaging of locale files


0.1.2 (2014-11-07)
==================

* Fix upload regular expressions for author and legend


0.1.1 (2014-11-03)
==================

* Fix missing SVG media in package


0.1.0 (2014-10-23)
==================

* Initial working version


