Metadata-Version: 2.4
Name: generate-labels
Version: 3.0.0
Summary: This package reads sample names from a file and arranges them on a sheet of A4 paper for printing on Avery-Zweckform L7871 labels
Author-email: Gleb Ebert <dev@gl-eb.me>
License-Expression: MIT
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama>=0.4.6
Dynamic: license-file

# Generate Avery L7871 Labels

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14288387.svg)](https://doi.org/10.5281/zenodo.14288387)

`generate-labels` reads sample names from a txt file (one name per line) and arranges them on a sheet of A4 paper so that they can be printed on **Avery-Zweckform L7871** labels.
The package is based on a python script (v2) which in turn was conceptually based on a bash script (v1).

## Requirements

- This package was developed primarily for a UNIX type **command-line interface** (e.g. Terminal on macOS), but it should also work on Windows
- **Python 3.13** or higher
- **TeX**, ideally the TeX Live distribution
  - `generate-labels` uses XeTeX as a typesetting engine
  - If you are not using TeX Live, make sure you have the required packages installed using the following command

    ```bash
    tlmgr install booktabs cm-unicode fontspec moresize oberdiek setspace tools
    ```

- You will need a **plain text file** (with the `.txt` suffix), ideally UTF-8 encoded, containing one sample name per line.
  Sample names should ideally be 30 characters long at most.
  Longer names could mess up the layout and prevent proper printing on the sticker sheet

## Installation

I recommend to install `generate-labels` using [`uv`](https://docs.astral.sh/uv/).

```bash
uv tool install generate-labels
```

Alternatively, you can also use `pip` or `pipx`.

```bash
pip install generate-labels
pipx install generate-labels
```

### Development Version

If you'd like to use the development version, I recommend to directly run it using `uv`.

```bash
uvx --from git+https://github.com/gl-eb/generate-stickers-AveryL7871@develop generate-labels
```

### Aliases

You can create an alias for `generate-labels` in your shell.
If you are using bash, add it to the `~/.bashrc` file in your home directory.
The equivalent file for zsh is `~/.zshrc`.
The following alias will change the current directory to one where you want your sticker files to live and then calls `generate-labels` from a subdirectory.

```bash
alias avery='cd ~/path/to/input_output_directory/ && generate-labels'
```

You can even use the alias in combination with command-line options

```bash
avery -i
```

## Usage

Open your command-line interface of choice and navigate to the folder that contains your input file.
The pdf file generated by this script will be placed in the same folder

```bash
cd path/to/your/folder
```

### Using Command-Line Options

If `generate-labels` is called and the path to a input file (`-f / --input-file`) is provided, the script runs without needing any input from the user.
Again, default values will be used for any unspecified options

```bash
generate-labels -f <path/to/input_file>
```

```bash
generate-labels -f <path/to/input_file> -o <path/to/output_file> -s 20 -d "July 1st 2023"
```

### Interactive Mode

Executing `generate-labels` without any command-line options will ask the user to interactively provide the minimum set of options necessary.
Currently this is just the input file (`-f / --input-file`).
The default values will be used for the remaining options

```bash
generate-labels
```

If the interactive mode (`-i / --interactive`) is activated, the user will be asked to provide any option that has not been set in the command line

```bash
generate-labels -i
```

```bash
generate-labels -i -f <path/to/input_file> -d none
```

### Suffixing Sample Names

Adding suffixes to sample names (e.g. appending the name of an experimental treatment) can currently only be done interactively.
One use case for suffixing is a set of microbial strains of cell lines that went through multiple treatment arms of an experiment in multiple replicates:

- Say you have three strains: Strain1, Strain2, Strain3
- The first suffix group could then be the treatment: Control, Treatment1, Treatment2
- Numbered replicate lines would be suffix group number two: 1, 2, 3

The resulting stickers would then be `Strain1-Control-1, Strain1-Control-2, Strain1-Control-3, Strain1-Treatment1-1, ... , Strain3-Treatment2-3`.
Please keep in mind that adding suffixes can push sample names above the recomended limit of 30 characters.
Check the resulting PDF carefully before printing

```bash
generate-labels -f <path/to/input_file> -a
```

### Command-Line Options

```
> generate-labels -h
usage: generate-labels.py [-h] [-i] [-f FILE] [-o FILE] [-a] [-s INT] [-d STR]

options:
  -h, --help            show this help message and exit
  -i, --interactive     run generate-labels in interactive mode, requiring user input for any unset arguments
  -f FILE, --input-file FILE
                        path to the text file containing one sample name per line
  -o FILE, --output-file FILE
                        name of or path to the output file (default: same as input file)
  -a, --add-suffixes    interactively add suffixes to sample names
  -s INT, --skip INT    number of stickers to skip (default: 0)
  -d STR, --date STR    "today", "none", or a custom date string(default: "today")
```
