entry_script

Definition

Entry script is a term describing the command a user types into its shell to execute:

./path/to/script

Clarification

A user may also start any binary executable that way, but in the context of protoprimer, the phrase "entry script" narrows down specifically to those commands implemented as text scripts primarily because they often have to be very primitive to create.

They serve two purposes:

  • they should be relatively easy for user to type

  • they should not do anything but delegate executing complex logic somewhere else

In short, they are primitive delegators.

Why primitive delegators?

Entry scripts should be kept primitive because they are harder to test:

  • they are outside of venv which makes it difficlut to execute reliably

  • they can be shell scripts that lack test-ability (see python_vs_shell)

Ideally, they serve as only as an entry point to launch the rest of the code (which is supposed to be inside venv within installed modules).

How to delegate?

Entry scripts are started by the user shell and their python is unpredictable - see python_executable.

The main job for entry scripts is to figure out how to delegate the execution to a module inside venv.

Options for venv activation:

  • The fastest option is to use (generated) shebang pointing to a python binary from venv.

    This is a less flexible approach with limits on the maximum length of shebang line - see shebang_line.

  • A slower alternative is to run a helper function which does the job.

    This is what protoprimer is designed for - see proto_code.

    In fact, there are two helper functions - see:

TODO: Implement generated_entry_script.

Special case: proto_code

It is possible to run proto_code as an entry script directly (see min env_layout), for example:

./cmd/proto_code/proto_kernel.py -h

In that case, the internal logic is not primitive (as it executes the core of the protoprimer).

However, because it is a copy of protoprimer.primer_kernel, it is still test-able inside venv.