django-components/docs/reference/commands.md

Commands

These are all the Django management commands that will be added by installing django_components:

components

usage: python manage.py  components [-h] {create,upgrade,ext} ...

See source code

The entrypoint for the 'components' commands.

Options:

• -h, --help
  • show this help message and exit

Subcommands:

• create
  • Create a new django component.
• upgrade
  • Upgrade django components syntax from '{% component_block ... %}' to '{% component ... %}'.
• ext
  • Run extension commands.

The entrypoint for the "components" commands.

python manage.py components start <name>
python manage.py components upgrade <name>
python manage.py components ext list
python manage.py components ext run <extension> <command>

components create

usage: python manage.py components create [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose]
              [--dry-run]
              name

See source code

Create a new django component.

Positional Arguments:

• name
  • The name of the component to create. This is a required argument.

Options:

• -h, --help
  • show this help message and exit
• --path PATH
  • The path to the component's directory. This is an optional argument. If not provided, the command will use the COMPONENTS.dirs setting from your Django settings.
• --js JS
  • The name of the JavaScript file. This is an optional argument. The default value is script.js.
• --css CSS
  • The name of the CSS file. This is an optional argument. The default value is style.css.
• --template TEMPLATE
  • The name of the template file. This is an optional argument. The default value is template.html.
• --force
  • This option allows you to overwrite existing files if they exist. This is an optional argument.
• --verbose
  • This option allows the command to print additional information during component creation. This is an optional argument.
• --dry-run
  • This option allows you to simulate component creation without actually creating any files. This is an optional argument. The default value is False.

Usage

To use the command, run the following command in your terminal:

python manage.py components create <name> --path <path> --js <js_filename> --css <css_filename> --template <template_filename> --force --verbose --dry-run

Replace <name>, <path>, <js_filename>, <css_filename>, and <template_filename> with your desired values.

Examples

Here are some examples of how you can use the command:

Creating a Component with Default Settings

To create a component with the default settings, you only need to provide the name of the component:

python manage.py components create my_component

This will create a new component named my_component in the components directory of your Django project. The JavaScript, CSS, and template files will be named script.js, style.css, and template.html, respectively.

Creating a Component with Custom Settings

You can also create a component with custom settings by providing additional arguments:

python manage.py components create new_component --path my_components --js my_script.js --css my_style.css --template my_template.html

This will create a new component named new_component in the my_components directory. The JavaScript, CSS, and template files will be named my_script.js, my_style.css, and my_template.html, respectively.

Overwriting an Existing Component

If you want to overwrite an existing component, you can use the --force option:

python manage.py components create my_component --force

This will overwrite the existing my_component if it exists.

Simulating Component Creation

If you want to simulate the creation of a component without actually creating any files, you can use the --dry-run option:

python manage.py components create my_component --dry-run

This will simulate the creation of my_component without creating any files.

components upgrade

usage: python manage.py components upgrade [-h] [--path PATH]

See source code

Upgrade django components syntax from '{% component_block ... %}' to '{% component ... %}'.

Options:

• -h, --help
  • show this help message and exit
• --path PATH
  • Path to search for components

components ext

usage: python manage.py components ext [-h] {list,run} ...

See source code

Run extension commands.

Options:

• -h, --help
  • show this help message and exit

Subcommands:

• list
  • List all extensions.
• run
  • Run a command added by an extension.

Run extension commands.

python manage.py components ext list
python manage.py components ext run <extension> <command>

components ext list

usage: python manage.py components ext list [-h] [-v {0,1}]

See source code

List all extensions.

Options:

• -h, --help
  • show this help message and exit
• -v {0,1}, --verbosity {0,1}
  • Verbosity level; 0=minimal output, 1=normal output

List all extensions.

python manage.py components ext list

Prints the list of installed extensions:

Installed extensions:
view
my_extension

If you need to omit the title in order to programmatically post-process the output, you can use the --verbosity (or -v) flag:

python manage.py components ext list -v 0

Which prints just:

view
my_extension

components ext run

usage: python manage.py components ext run [-h]

See source code

Run a command added by an extension.

Options:

• -h, --help
  • show this help message and exit

Run a command added by an extension.

Each extension can add its own commands, which will be available to run with this command.

For example, if you define and install the following extension:

from django_components import ComponentCommand, ComponentExtension

class HelloCommand(ComponentCommand):
    name = "hello"
    help = "Say hello"
    def handle(self, *args, **kwargs):
        print("Hello, world!")

class MyExt(ComponentExtension):
    name = "my_ext"
    commands = [HelloCommand]

You can run the hello command with:

python manage.py components ext run my_ext hello

You can also define arguments for the command, which will be passed to the command's handle method.

from django_components import CommandArg, ComponentCommand, ComponentExtension

class HelloCommand(ComponentCommand):
    name = "hello"
    help = "Say hello"
    arguments = [
        CommandArg(name="name", help="The name to say hello to"),
        CommandArg(name=["--shout", "-s"], action="store_true"),
    ]

    def handle(self, name: str, *args, **kwargs):
        shout = kwargs.get("shout", False)
        msg = f"Hello, {name}!"
        if shout:
            msg = msg.upper()
        print(msg)

You can run the command with:

python manage.py components ext run my_ext hello --name John --shout

!!! note

Command arguments and options are based on Python's `argparse` module.

For more information, see the [argparse documentation](https://docs.python.org/3/library/argparse.html).

upgradecomponent

usage: upgradecomponent [-h] [--path PATH] [--version] [-v {0,1,2,3}] [--settings SETTINGS]
                        [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]
                        [--skip-checks]

See source code

Deprecated. Use components upgrade instead.

Options:

• -h, --help
  • show this help message and exit
• --path PATH
  • Path to search for components
• --version
  • Show program's version number and exit.
• -v {0,1,2,3}, --verbosity {0,1,2,3}
  • Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
• --settings SETTINGS
  • The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
• --pythonpath PYTHONPATH
  • A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
• --traceback
  • Raise on CommandError exceptions.
• --no-color
  • Don't colorize the command output.
• --force-color
  • Force colorization of the command output.
• --skip-checks
  • Skip system checks.

Deprecated. Use components upgrade instead.

startcomponent

usage: startcomponent [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force]
                      [--verbose] [--dry-run] [--version] [-v {0,1,2,3}] [--settings SETTINGS]
                      [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]
                      [--skip-checks]
                      name

See source code

Deprecated. Use components create instead.

Positional Arguments:

• name
  • The name of the component to create. This is a required argument.

Options:

• -h, --help
  • show this help message and exit
• --path PATH
  • The path to the component's directory. This is an optional argument. If not provided, the command will use the COMPONENTS.dirs setting from your Django settings.
• --js JS
  • The name of the JavaScript file. This is an optional argument. The default value is script.js.
• --css CSS
  • The name of the CSS file. This is an optional argument. The default value is style.css.
• --template TEMPLATE
  • The name of the template file. This is an optional argument. The default value is template.html.
• --force
  • This option allows you to overwrite existing files if they exist. This is an optional argument.
• --verbose
  • This option allows the command to print additional information during component creation. This is an optional argument.
• --dry-run
  • This option allows you to simulate component creation without actually creating any files. This is an optional argument. The default value is False.
• --version
  • Show program's version number and exit.
• -v {0,1,2,3}, --verbosity {0,1,2,3}
  • Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
• --settings SETTINGS
  • The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
• --pythonpath PYTHONPATH
  • A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
• --traceback
  • Raise on CommandError exceptions.
• --no-color
  • Don't colorize the command output.
• --force-color
  • Force colorization of the command output.
• --skip-checks
  • Skip system checks.

Deprecated. Use components create instead.