{"id":16843391,"url":"https://github.com/barttc/django-attachments","last_synced_at":"2025-04-09T04:06:54.461Z","repository":{"id":564181,"uuid":"195323","full_name":"bartTC/django-attachments","owner":"bartTC","description":"A generic Django application to attach Files (Attachments) to any model.","archived":false,"fork":false,"pushed_at":"2024-04-15T22:54:27.000Z","size":204,"stargazers_count":297,"open_issues_count":8,"forks_count":90,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-23T02:01:42.418Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bartTC.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"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}},"created_at":"2009-05-07T21:26:52.000Z","updated_at":"2025-03-12T03:23:42.000Z","dependencies_parsed_at":"2023-01-13T10:29:18.363Z","dependency_job_id":"f66ad42e-5ea0-4e2a-8b43-2a19d505c861","html_url":"https://github.com/bartTC/django-attachments","commit_stats":{"total_commits":174,"total_committers":24,"mean_commits":7.25,"dds":0.3793103448275862,"last_synced_commit":"ff184d68993b026e787f140257ef3f1f00fb1f67"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartTC%2Fdjango-attachments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartTC%2Fdjango-attachments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartTC%2Fdjango-attachments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bartTC%2Fdjango-attachments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bartTC","download_url":"https://codeload.github.com/bartTC/django-attachments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247974732,"owners_count":21026742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-10-13T12:50:50.481Z","updated_at":"2025-04-09T04:06:54.433Z","avatar_url":"https://github.com/bartTC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://badge.fury.io/py/django-attachments.svg\n    :target: https://badge.fury.io/py/django-attachments\n\n.. image:: https://travis-ci.org/bartTC/django-attachments.svg?branch=master\n    :target: https://travis-ci.org/bartTC/django-attachments\n\n.. image:: https://api.codacy.com/project/badge/Grade/e13db6df2a2148b08c662798642aa611\n    :alt: Codacy Badge\n    :target: https://app.codacy.com/app/bartTC/django-attachments\n\n.. image:: https://api.codacy.com/project/badge/Coverage/e13db6df2a2148b08c662798642aa611\n    :target: https://www.codacy.com/app/bartTC/django-attachments\n\n==================\ndjango-attachments\n==================\n\ndjango-attachments is a generic set of template tags to attach any kind of\nfiles to models.\n\nInstallation:\n=============\n\n1. Put ``attachments`` to your ``INSTALLED_APPS`` in your ``settings.py``\n   within your django project:\n   \n   .. code-block:: python\n\n        INSTALLED_APPS = (\n            ...\n            'attachments',\n        )\n\n2. Add the attachments urlpattern to your ``urls.py``:\n\n   .. code-block:: python\n\n        url(r'^attachments/', include('attachments.urls', namespace='attachments')),\n\n3. Migrate your database:\n\n   .. code-block:: shell\n\n        ./manage.py migrate\n\n4. Grant the user some permissions:\n\n   * For **adding attachments** grant the user (or group) the permission\n     ``attachments.add_attachment``.\n\n   * For **deleting attachments** grant the user (or group) the permission\n     ``attachments.delete_attachment``. This allows the user to delete their\n     attachments only.\n\n   * For **deleting foreign attachments** (attachments by other users) grant\n     the user the permission ``attachments.delete_foreign_attachments``.\n\n5. Set ``DELETE_ATTACHMENTS_FROM_DISK`` to ``True`` if you want to remove\n   files from disk when Attachment objects are removed!\n\n6. Configure ``FILE_UPLOAD_MAX_SIZE`` (optional). This is the maximum size in\n   bytes before raising form validation errors. If not set there is no restriction\n   on file size.\n\nMind that you serve files!\n==========================\n\ndjango-attachments stores the files in your site_media directory and does not modify\nthem. For example, if an user uploads a .html file your webserver will probably display\nit in HTML. It's a good idea to serve such files as plain text. In a Apache2\nconfiguration this would look like:\n\n.. code-block:: apache\n\n    \u003cLocation /site_media/attachments\u003e\n        AddType text/plain .html .htm .shtml .php .php5 .php4 .pl .cgi\n    \u003c/Location\u003e\n\n\nHouse-keeping\n=============\n\ndjango-attachments provides the ``delete_stale_attachments`` management command.\nIt will remove all attachments for which the related objects don't exist anymore!\nSys-admins could then:\n\n.. code-block:: shell\n\n    ./manage.py delete_stale_attachments\n\nYou may also want to execute this via cron.\n\n\nLocal development\n=================\n\nInstalling a local devel environment with ``pipenv``.\nIt creates a virtualenv for you with the right ENV variables loaded from ``.env``.\n\n   .. code-block:: shell\n\n        # pip install pipenv\n\n        $ pipenv install\n        Loading .env environment variables...\n        Installing dependencies from Pipfile.lock (a053bc)...\n        To activate this project's virtualenv, run pipenv shell.\n        Alternatively, run a command inside the virtualenv with pipenv run.\n\n\nTests\n=====\n\nRun the testsuite in your local environment using ``pipenv``:\n\n.. code-block:: shell\n\n    $ cd django-attachments/\n    $ pipenv install --dev\n    $ pipenv run pytest attachments/\n\nOr use tox to test against various Django and Python versions:\n\n.. code-block:: shell\n\n    $ tox -r\n\nYou can also invoke the test suite or other 'manage.py' commands by calling\nthe ``django-admin`` tool with the test app settings:\n\n.. code-block:: shell\n\n    $ cd django-attachments/\n    $ pipenv install --dev\n    $ pipenv run test\n    $ pipenv run django-admin.py runserver\n    $ pipenv run django-admin makemigrations --dry-run\n\n\nBuilding a new release\n======================\n\n   .. code-block:: shell\n\n        $ git tag\n        $ change version in setup.cfg\n        $ pip install -U setuptools\n        $ python setup.py sdist \u0026\u0026 python setup.py bdist_wheel --universal\n        $ twine upload --sign dist/*\n\nUsage:\n======\n\nIn contrib.admin:\n-----------------\n\ndjango-attachments provides a inline object to add a list of attachments to\nany kind of model in your admin app.\n\nSimply add ``AttachmentInlines`` to the admin options of your model. Example:\n\n.. code-block:: python\n\n    from django.contrib import admin\n    from attachments.admin import AttachmentInlines\n\n    class MyEntryOptions(admin.ModelAdmin):\n        inlines = (AttachmentInlines,)\n\n.. image:: http://cloud.github.com/downloads/bartTC/django-attachments/attachments_screenshot_admin.png\n\nIn your frontend templates:\n---------------------------\n\nFirst of all, load the attachments_tags in every template you want to use it:\n\n.. code-block:: html+django\n\n    {% load attachments_tags %}\n\ndjango-attachments comes with some templatetags to add or delete attachments\nfor your model objects in your frontend.\n\n1. ``get_attachments_for [object]``: Fetches the attachments for the given\n   model instance. You can optionally define a variable name in which the attachment\n   list is stored in the template context (this is required in Django 1.8). If\n   you do not define a variable name, the result is printed instead.\n\n   .. code-block:: html+django\n\n        {% get_attachments_for entry as attachments_list %}\n\n2. ``attachments_count [object]``: Counts the attachments for the given\n   model instance and returns an int:\n\n   .. code-block:: html+django\n\n        {% attachments_count entry %}\n\n3. ``attachment_form``: Renders a upload form to add attachments for the given\n   model instance. Example:\n\n   .. code-block:: html+django\n\n        {% attachment_form [object] %}\n\n   It returns an empty string if the current user is not logged in.\n\n4. ``attachment_delete_link``: Renders a link to the delete view for the given\n   *attachment*. Example:\n\n   .. code-block:: html+django\n\n        {% for att in attachments_list %}\n            {{ att }} {% attachment_delete_link att %}\n        {% endfor %}\n\n   This tag automatically checks for permission. It returns only a html link if the\n   give n attachment's creator is the current logged in user or the user has the\n   ``delete_foreign_attachments`` permission.\n\nQuick Example:\n==============\n\n.. code-block:: html+django\n\n    {% load attachments_tags %}\n    {% get_attachments_for entry as my_entry_attachments %}\n\n    \u003cspan\u003eObject has {% attachments_count entry %} attachments\u003c/span\u003e\n    {% if my_entry_attachments %}\n    \u003cul\u003e\n    {% for attachment in my_entry_attachments %}\n        \u003cli\u003e\n            \u003ca href=\"{{ attachment.attachment_file.url }}\"\u003e{{ attachment.filename }}\u003c/a\u003e\n            {% attachment_delete_link attachment %}\n        \u003c/li\u003e\n    {% endfor %}\n    \u003c/ul\u003e\n    {% endif %}\n\n    {% attachment_form entry %}\n\n    {% if messages %}\n    \u003cul class=\"messages\"\u003e\n    {% for message in messages %}\n        \u003cli{% if message.tags %} class=\"{{ message.tags }}\"{% endif %}\u003e\n            {{ message }}\n        \u003c/li\u003e\n    {% endfor %}\n    \u003c/ul\u003e\n    {% endif %}\n\nSettings\n========\n\n- ``DELETE_ATTACHMENTS_FROM_DISK`` will delete attachment files when the\n  attachment model is deleted. **Default False**!\n- ``FILE_UPLOAD_MAX_SIZE`` in bytes. Deny file uploads exceeding this value.\n  **Undefined by default**.\n- ``AppConfig.attachment_validators`` - a list of custom form validator functions\n  which will be executed against uploaded files. If any of them raises\n  ``ValidationError`` the upload will be denied. **Empty by default**. See\n  ``attachments/tests/testapp/apps.py`` for an example.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarttc%2Fdjango-attachments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarttc%2Fdjango-attachments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarttc%2Fdjango-attachments/lists"}