{"id":15907967,"url":"https://github.com/pyscaffold/pyscaffoldext-django","last_synced_at":"2025-03-21T21:31:50.917Z","repository":{"id":37955763,"uuid":"196068481","full_name":"pyscaffold/pyscaffoldext-django","owner":"pyscaffold","description":" :horse: PyScaffold extension that calls on `django-admin` on project creation","archived":false,"fork":false,"pushed_at":"2025-03-03T17:02:45.000Z","size":133,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T05:34:29.773Z","etag":null,"topics":["django","pyscaffold","pyscaffold-extension","python"],"latest_commit_sha":null,"homepage":"https://pyscaffold.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyscaffold.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-09T19:12:35.000Z","updated_at":"2023-08-26T21:23:51.000Z","dependencies_parsed_at":"2023-02-19T11:00:42.021Z","dependency_job_id":"b720bf98-b005-4af2-9037-c431a50fc3ea","html_url":"https://github.com/pyscaffold/pyscaffoldext-django","commit_stats":{"total_commits":156,"total_committers":5,"mean_commits":31.2,"dds":"0.33974358974358976","last_synced_commit":"68045ddeee706a1426813e445c305d37dcb8dd4c"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyscaffold%2Fpyscaffoldext-django","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyscaffold%2Fpyscaffoldext-django/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyscaffold%2Fpyscaffoldext-django/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyscaffold%2Fpyscaffoldext-django/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyscaffold","download_url":"https://codeload.github.com/pyscaffold/pyscaffoldext-django/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244874383,"owners_count":20524577,"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":["django","pyscaffold","pyscaffold-extension","python"],"created_at":"2024-10-06T14:07:55.576Z","updated_at":"2025-03-21T21:31:50.478Z","avatar_url":"https://github.com/pyscaffold.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://api.cirrus-ci.com/github/pyscaffold/pyscaffoldext-django.svg?branch=master\n    :alt: Built Status\n    :target: https://cirrus-ci.com/github/pyscaffold/pyscaffoldext-django\n.. image:: https://readthedocs.org/projects/pyscaffoldext-django/badge/?version=latest\n    :alt: ReadTheDocs\n    :target: https://pyscaffold.org/projects/django/en/latest/\n.. image:: https://img.shields.io/coveralls/github/pyscaffold/pyscaffoldext-django/master.svg\n    :alt: Coveralls\n    :target: https://coveralls.io/r/pyscaffold/pyscaffoldext-django\n.. image:: https://img.shields.io/pypi/v/pyscaffoldext-django.svg\n    :alt: PyPI-Server\n    :target: https://pypi.org/project/pyscaffoldext-django/\n.. image:: https://pepy.tech/badge/pyscaffoldext-django/month\n    :alt: Monthly Downloads\n    :target: https://pepy.tech/project/pyscaffoldext-django\n\n====================\npyscaffoldext-django\n====================\n\n\n    Integration of **Django**'s built-in generator (``django-admin``)\n    into **PyScaffold**\n\n`PyScaffold`_ is a development tool focused in distributable Python packages.\nThis extension allows the development of `Django`_ websites using\nPyScaffold sensible project structure, by tapping into the `django-admin`_ cli.\n\n    **LOOKING FOR CONTRIBUTORS** - If you use PyScaffold or Django and would\n    like to help us as a contributor (or even as one of the maintainers) for\n    this extension, please send us an email or open an issue, we would love to\n    have you on board.\n\n\nQuickstart\n==========\n\nThis extension can be directly installed with ``pip``:\n\n.. code-block:: bash\n\n    pip install pyscaffoldext-django\n\nOr, if you prefer ``pipx``:\n\n.. code-block:: shell\n\n    pipx install pyscaffold  # if you haven't installed pyscaffold yet\n    pipx inject pyscaffold pyscaffoldext-django\n\nNote that, after the installation, ``putup -h`` will show a new option\n``--django``. Use this option to indicate when you are trying to create a\ndjango app. For example:\n\n.. code-block:: shell\n\n    putup --django myapp\n\nPlease refer to `django-admin`_ documentation for more details.\n\n\nAlternative Procedure\n=====================\n\nUsing Django extension in PyScaffold is roughly equivalent to first create\nan app using `django-admin`_ and then convert it to PyScaffold.\nThe following manual procedure can be used to replace ``pyscaffoldext-django``:\n\n.. code-block:: bash\n\n    django-admin startproject myapp\n    mkdir myapp/src\n    mv myapp/myapp myapp/src\n    mv myapp/manage.py myapp/src/myapp/__main__.py\n\n    # edit the location of the database in myapp/src/myapp/setttings.py\n    # to point to one directory up, similar to:\n    #\n    #   PROJECT_DIR = os.path.dirname(BASE_DIR)\n    #   DATABASES = {'default': { ..., 'NAME': os.path.join(PROJECT_DIR, 'db.sqlite3')}}\n\n    putup myapp --force\n\nWe move/rename the ``manage.py`` file to ``myapp/src/myapp/__main__.py``. This\nmakes it possible to manage the application using ``python -m myapp`` when\nit is installed as a package (instead of ``python manage.py``).\nAll the arguments remain the same.\nPlease check the next section for more information.\n\nRunning the script with ``python -m`` requires your package to be installed\n(a simple ``pip install -e .`` will suffice), however we also generate a new\n``manage.py`` file that is a simple stub pointing to the ``__main__.py`` and\nworks without explicit installation.\n\nFor complex use cases, maybe a better option is to do the conversion\nmanually. If you find problems running PyScaffold with ``--django``\nplease try to execute this procedure.\n\n\nDistributable Django Packages\n=============================\n\nDjango is a framework for creating web applications, and PyScaffold is a tool\nthat helps to build re-usable, distributable packages - which most of the time\ncorrespond to libraries or command line tools.\n\n.. _dependencies:\n\nWhile those two definitions are not mutually exclusive, it is a bit tricky to\ncreate a package with PyScaffold that serves a Django app.\nThe first reason is that applications usually require concrete dependencies\n(pinned version numbers), while libraries are more relaxed and tend to use\nabstract dependencies (ranges of version numbers). You can read all about the\ndifferences between those two approaches in `PyScaffold's documentation`_,\nhowever the main point is: when creating packages for webapps you have two options\n\n:Use concrete dependencies: pin the exact version number for your\n  dependencies to avoid bugs (*it works on my machine*\\ :sup:`TM`), but\n  instruct your users that the package should be installed within a\n  **dedicated** `virtual environment`_ to avoid dependency hell; or\n:Use abstract dependencies: prefer relaxed dependency ranges (e.g. relying\n  on stable APIs of  dependencies that use `semver`_), but test extensively\n  your module against different installed versions to make sure nothing breaks\n  (`tox`_ and `nox`_ are good tools for that).\n\n.. _managepy:\n\nThe second reason is that Django expects the user of your application to have\ncontrol on where the source code is placed, and this simply doesn't go well with\npip installing locations deeply hidden somewhere in the file system (e.g.\n``/home/username/my-venvs/web-app/lib/python3.6/site-packages/my-web-app``)…\n\nFor example, before starting a Django application server you are supposed to run\nmigrations to prepare the correct structure in the database to receive your\ndata. This is usually achieved by running ``python manage.py migrate`` at the\nroot of your directory, however, if someone is installing your app using pip,\nhow does this person knows where to find the ``manage.py`` file?\n\nTo solve this problem, ``pyscaffoldext-django`` renames ``manage.py`` to\n|mainpy|_ and moves it inside your web application package. Since it becomes\npart of your package, the script will be accessible via ``python -m YOUR_PACKAGE_NAME\n\u003ccommands\u003e`` from everywhere in the system, and therefore no one installing it\nwith pip needs to know where it is.\n\n.. _database:\n\nAnother example of the same behaviour is the default SQLite database Django\ncreates. If you simply turn an Django app that was not created with PyScaffold into a\npackage, install it and run the migrations, Django will generate an SQLite file\nin an arbitrary location in your disk. PyScaffold cannot automatically solve\nthis problem for you. Instead you can follow a few approaches:\n\n#. (*NOT RECOMMENDED*) place your SQLite database inside your package and\n   distribute it as a `package data`_, accessing it via `importlib.resources`_.\n   (Please note resources are supposed to be immutable and not re-written to disk)\n#. Allow the person installing your package to specify a different\n   configuration via environment variables. According to the `Mozilla's\n   tutorials`_, the library `dj-database-url`_ is good for that.\n#. Place your SQLite database `somewhere in the user home`_.\n\nFor the sake of pragmatism, PyScaffold will reconfigure ``settings.py`` to\nplace the database inside the project root in the development environment, but\nit is your responsibility to change this when going into production.\n\n.. _multiple-apps:\n\nFinally, it is important to notice that, while it is popular in the Django community\nto create separated top-level folders for independent applications, this is more or less\nincompatible with the concept of a Python package...\nOne entry in PyPI should install a single package in your machine. Ideally, if\nyou use `multiple apps`_, you should deploy a different package for each of\nthem and declare them as dependencies of your main project.\nAlternatively you can also deploy new applications nested inside of your main\nproject package (the one generated by PyScaffold/``django-admin startproject``).\nTherefore, caution is required when using ``python manage.py startapp`` (you\nshould either provide the optional ``directory`` parameter as somewhere inside\nof your main package, or skip it completely).\nOne example on how to use nested apps is:\n\n.. code-block:: bash\n\n    putup --django website\n    cd website\n    # … do some coding\n    mkdir src/website/subapp\n    python manage.py startapp subapp src/website/subapp\n    # OR python -m website startapp subapp src/website/subapp\n    #    if you have the package installed in the dev environment\n    # … then you can add \"website.subapp\" to INSTALLED_APPS in src/website/settings.py\n    # … remeber to use relative imports or the full package name \"website.subapp\" when needed\n\n\nTips\n====\n\n#. Have a look on `Django's guides`_, but remember that PyScaffold already do\n   the heavy lifting for you (no need to write packaging configuration from\n   scratch) and that we use a `src-based layout`_\n#. Do not assume anything about the file system where the package will be\n   installed.\n#. If you really need to write things to disk, you can follow the `XDG standards`_\n   and write to ``$XDG_DATA_HOME`` (the package `appdirs`_ might help).\n#. Accept configurations via environment variables, and throw meaningful errors\n   when they are not provided. Even if you prefer reading configurations from a\n   file, you can always let the person installing your package to specify a\n   location for this file as an environment variable.\n#. Use environment variables as flags/switches to enable/disable features or\n   select alternative implementations.\n#. Be extra careful to not store secrets and confidential info in your source\n   repository.\n#. Be extra careful with secrets and confidential info **IN GENERAL**.\n   If really required to store them, use well known cryptography techniques and\n   tweak file/folder permissions in your operating system (e.g. the command\n   ``chmod og-rwx`` is your friend, but you can also consider ``400``\n   permissions). Instructing the person installing your package to create a\n   separated system account to run your web app with limited privileges might\n   also be good.\n#. Provide extensive documentation on how your users are supposed to install\n   and run your app (e.g. virtualenv installation instructions,\n   ngnix/apache/systemd configuration examples, etc...)\n\n\n.. _pyscaffold-notes:\n\nMaking Changes \u0026 Contributing\n=============================\n\nThis project uses `pre-commit`_, please make sure to install it before making any\nchanges::\n\n    pip install pre-commit\n    cd pyscaffoldext-django\n    pre-commit install\n\nIt is a good idea to update the hooks to the latest version::\n\n    pre-commit autoupdate\n\nPlease also check PyScaffold's `contribution guidelines`_,\n\nNote\n====\n\nThis project has been set up using PyScaffold 4.0a2. For details and usage\ninformation on PyScaffold see https://pyscaffold.org/.\n\n\n.. _PyScaffold: https://pyscaffold.org\n.. _PyScaffold's documentation: https://pyscaffold.org/en/latest/dependencies.html\n.. _Django: https://www.djangoproject.com/\n.. _django-admin: https://docs.djangoproject.com/en/3.2/ref/django-admin/\n.. _extension: https://pyscaffold.org/en/latest/extensions.html\n.. _virtual environment: https://docs.python.org/3/tutorial/venv.html\n.. _semver: https://semver.org\n.. _tox: https://tox.readthedocs.io/en/latest/example/basic.html#compressing-dependency-matrix\n.. _nox: https://nox.thea.codes/en/stable/config.html#parametrizing-sessions\n.. |mainpy| replace:: ``__main__.py``\n.. _mainpy: https://docs.python.org/3/library/__main__.html\n.. _package data: https://pyscaffold.org/en/latest/features.html#configuration-packaging-distribution\n.. _importlib.resources: https://docs.python.org/3/library/importlib.html#module-importlib.resources\n.. _Mozilla's tutorials: https://developer.mozilla.org/en-US/docs/Learn/Server-side/Django/Deployment\n.. _dj-database-url: https://pypi.org/project/dj-database-url/\n.. _XDG standards: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\n.. _somewhere in the user home: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\n.. _appdirs: https://pypi.org/project/appdirs/\n.. _Django's guides: https://docs.djangoproject.com/en/3.0/intro/reusable-apps/\n.. _multiple apps: https://developer.mozilla.org/en-US/docs/Learn/Server-side/Django/skeleton_website\n.. _src-based layout: https://blog.ionelmc.ro/2014/05/25/python-packaging/\n.. _pre-commit: https://pre-commit.com/\n.. _contribution guidelines: https://pyscaffold.org/en/latest/contributing.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyscaffold%2Fpyscaffoldext-django","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyscaffold%2Fpyscaffoldext-django","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyscaffold%2Fpyscaffoldext-django/lists"}