Command Line Tool

To get started, create a new Python file for your extension. Let’s name it hello_world.py. In this file, we will define the HelloWorld extension class.

Please ensure this file is within one of the configured source paths (project.source key in palgen.toml) or extension paths (palgen.extensions.folders key in palgen.toml), otherwise it will not be picked up. If you haven’t yet created a palgen.toml file please do so now.

Minimal command line tool extension

import logging
from palgen.ext import Extension

class HelloWorld(Extension):
    """ Description for this tool """

    # disable ingest
    ingest = None

    def run(self, files: list, jobs: Optional[int] = None) -> list:
        logging.info("hello world")

This does not use any of the pipelines.

Adding options

Options for our extension can be set either in palgen.toml or as command line options. So far our HelloWorld module does not have any options aside from the built-in ones (such as --help). To add some declare a subclass called Settings.

import logging
from typing import Annotated
from palgen.ext import Extension, Model

class HelloWorld(Extension):
    """ Description for this tool """

    # disable ingest
    ingest = None

    # options of this extension
    class Settings(Model):
      # This is sufficient to require `name` to exist and be of type `str`
      name: str

      # Settings can also be annotated with a help text
      greeting: Annotated[str, "The greeting to display"] = "Hello"

    def run(self, files: list, jobs: Optional[int] = None) -> list:
        logging.info("hello world")

Note that help texts can be added by using typing.Annotated as shown in the example above.

Full example

Here’s a thoroughly commented full example for a command line tool. It can be found in hello_world.py.

You can run it by invoking palgen helloworld --name somename within the examples/tutorial directory of this repository.

import logging
from typing import Annotated, Optional

from palgen import Extension, Model

# extension class must inherit from palgen.Extension
class HelloWorld(Extension):
    ''' Prints hello world '''
    # a docstring can be used to provide a help text

    # we don't need to ingest anything for now
    ingest = None

    # settings and command line options for this extension.
    # note that the `Settings` subclass must inherit from `Model`
    class Settings(Model):
        # This is sufficient to require `name` to exist and be of type `str`
        name: str

        # Settings can also be annotated with a help text
        greeting: Annotated[str, "The greeting to display"] = "Hello"

        repeat: int = 1         # Optional int, defaults to 1
        uppercase: bool = False # Optional flag, defaults to False


    # since we do not use data pipelines in this simple command line tool
    # we instead override `Extension.run(...)` directly
    def run(self, files: list, jobs: Optional[int] = None) -> list:

        # this extension's settings can be accessed using self.settings
        greeting = self.settings.greeting

        if self.settings.uppercase:
            greeting = greeting.upper()

        for _ in range(self.settings.repeat):
            # `logging` should be prefered over `print` for output consistency
            logging.info("%s, %s", greeting, self.settings.name)


        # we didn't produce any files, so return an empty list or `None`

        # note that `return None`, `return` and no return statements whatsoever
        # are equivalent in Python. Any empty iterable would be fine too.
        return []