Metadata-Version: 2.4
Name: django-keygen
Version: 0.1.1
Summary: django-keygen is a Django management command utility designed to securely generate cryptographic secret keys.
Author-email: Mouhib sellami <mouhib.sellami@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mouhib-Sellami/django-keygen
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: django>=4.2
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

django-keygen
=============

django-keygen is a Django management command utility for securely generating
cryptographic secret keys and passwords, and optionally writing them into your
project's environment (``.env``) files automatically.

Detailed documentation will be available in the "docs" directory.

Installation
------------

Install via pip::

    pip install django-keygen

Or install the latest version directly from GitHub::

    pip install git+https://github.com/mouhib-Sellami/django-keygen.git

Quick start
-----------

1. Add ``django_keygen`` to your ``INSTALLED_APPS``::

    INSTALLED_APPS = [
        ...,
        'django_keygen',
    ]

Commands Overview
-----------------

django-keygen provides three management commands:

+---------------------------+-------------------------------------------------------+
| Command                   | Purpose                                               |
+===========================+=======================================================+
| ``keygen``                | Generate secret keys and/or passwords into a named    |
|                           | ``.env`` file. The recommended all-in-one command.    |
+---------------------------+-------------------------------------------------------+
| ``generate_django_secret``| Dedicated command for generating a single             |
|                           | ``DJANGO_SECRET_KEY`` and optionally writing it to    |
|                           | an env file via an interactive or flag-driven flow.   |
+---------------------------+-------------------------------------------------------+
| ``generate_password``     | Interactive terminal interface for generating and     |
|                           | tweaking secure passwords.                            |
+---------------------------+-------------------------------------------------------+

----

1. ``keygen`` — Unified Key & Password Generator
-------------------------------------------------

The ``keygen`` command is the recommended way to generate one or more secret
keys and/or passwords and write them into an environment file in a single step.
Variable names are passed directly as arguments, so each generated value is
stored under the name you choose.

**Positional arguments:**

* ``SECRET [SECRET ...]``
    One or more variable names to generate a Django secret key for (e.g.
    ``SECRET_KEY API_KEY``). Each name receives its own independently generated
    cryptographic key.

**Flags:**

* ``--passwords PASSWORDS [PASSWORDS ...]``, ``-p``
    One or more variable names to generate a secure password for instead of a
    Django secret key (e.g. ``-p DB_PASSWORD REDIS_PASSWORD``).

* ``--file FILE``, ``-f``
    Path to the env file, relative to ``BASE_DIR`` (default: ``.env``). If the
    file does not exist, the command offers to create it.

* ``--append``
    Update the existing file in place rather than recreating it from scratch.
    Without this flag the file is fully rewritten (all previous content is
    preserved but reformatted alongside the new values). Prompts a confirmation
    warning because replacing an active ``SECRET_KEY`` invalidates all existing
    sessions, tokens, and signed cookies.

* ``--no-input``
    Skip all confirmation prompts. Useful for automated deployments, Docker
    entrypoints, and CI/CD pipelines.

**Examples**::

    # Generate SECRET_KEY and write it to .env (recreates the file)
    python manage.py keygen SECRET_KEY

    # Generate two secret keys into a specific file, no prompts
    python manage.py keygen SECRET_KEY API_KEY --file .env.production --no-input

    # Generate a secret key and two passwords into .env.local, appending
    python manage.py keygen SECRET_KEY --passwords DB_PASSWORD REDIS_PASSWORD \
        --file .env.local --append

    # Generate only passwords (no secret keys)
    python manage.py keygen --passwords DB_PASSWORD --file .env

----

2. ``generate_django_secret`` — Dedicated Secret Key Command
-------------------------------------------------------------

The ``generate_django_secret`` command is dedicated to generating a single
Django secret key stored under the ``DJANGO_SECRET_KEY`` variable. Run it
without any flags to simply print a key to the terminal, or add ``--append``
to write it to an env file.

When writing to a file, the command either accepts a path via ``--file`` or
launches an interactive file-selection menu that scans your project for
existing ``.env*`` files.

**Flags:**

* ``--append``
    Write the generated key to an environment file. Without this flag the key
    is only printed to stdout — no files are touched. Prompts a confirmation
    warning because replacing a live ``SECRET_KEY`` invalidates all existing
    sessions, tokens, and signed cookies.

* ``--file FILE``, ``-f``
    Directly specify the env file to update (e.g. ``-f .env.production``),
    bypassing the interactive selection menu. If the file does not exist it is
    created automatically. Only used together with ``--append``.

* ``--no-input``
    Suppress all interactive prompts, menus, and risk warnings. Useful for
    automated deployments and CI/CD pipelines.

**Examples**::

    # Print a new secret key to the terminal only (no file changes)
    python manage.py generate_django_secret

    # Interactively choose which env file to update
    python manage.py generate_django_secret --append

    # Write directly to a specific file, no prompts
    python manage.py generate_django_secret --append --no-input -f .env.local

**After running**, update your ``settings.py`` to read the key from the
environment::

    import os
    SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')

----

3. ``generate_password`` — Interactive Password Generator
---------------------------------------------------------

The ``generate_password`` command launches an interactive terminal session for
generating and refining secure passwords. After each password is shown, you can
regenerate it or adjust the composition settings without restarting the command.

**Flags** (set initial defaults; all can be changed interactively):

* ``--length LENGTH``, ``-len``
    Desired password length (default: 12).

* ``--letters``
    Include lowercase letters (a–z).

* ``--uppercase``
    Include uppercase letters (A–Z).

* ``--numbers``
    Include numerical digits (0–9).

* ``--symbol``
    Include symbols and punctuation characters.

* ``--secure``
    Shortcut that forces uppercase letters, numbers, symbols, and a minimum
    length of 20. Overrides individual composition flags.

**Examples**::

    # Launch with defaults (12 characters, no composition constraints)
    python manage.py generate_password

    # Start with a longer length and reconfigure interactively
    python manage.py generate_password --length 16

    # Instantly generate a highly secure 20-character password
    python manage.py generate_password --secure

----

Programmatic Usage
------------------

The underlying password generator can be imported directly into your own
Django apps — useful for custom registration flows, invitation tokens, or
background tasks::

    from django_keygen.core.passwords import generate_password

    # Generate a secure password with specific character sets
    new_password = generate_password(
        length=14,
        use_uppercase=True,
        use_numbers=True,
        use_symbols=True,
    )

    # Use it in your application logic
    from django.contrib.auth.models import User
    user = User.objects.create_user(username='johndoe', email='john@example.com')
    user.set_password(new_password)
    user.save()

----

License
-------

django-keygen is released under the **MIT License**.

Copyright (c) 2026 Mouhib Sellami

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

See the ``LICENSE`` file in the repository root for the full license text,
or visit: https://github.com/mouhib-Sellami/django-keygen/blob/main/LICENSE
