UDAPI

Common errors

• command not found: udapy

  cause The `udapy` command-line script, installed by `pip`, is not in your system's `PATH` environment variable. This often happens with user-specific installations (`pip install --user`) if the local bin directory isn't added to PATH.
  fix Add the pip-installed scripts directory (usually `~/.local/bin`) to your `PATH` environment variable: `export PATH="$HOME/.local/bin/:$PATH"`. You may also want to add this line to your shell's configuration file (e.g., `.bashrc` or `.zshrc`).

• ModuleNotFoundError: No module named 'ufal.udpipe'

  cause You are trying to use a `udapi` block that relies on the `ufal.udpipe` library, but `ufal.udpipe` has not been installed. It is an optional dependency.
  fix Install the `ufal.udpipe` library: `pip install --upgrade ufal.udpipe`.

• SyntaxError: invalid syntax (or similar errors like IndentationError) when running `udapi` code

  cause The Python version being used is older than the required Python 3.9. While the specific error might seem generic, it's often an underlying incompatibility with the required Python version.
  fix Upgrade your Python environment to version 3.9 or newer. Use a tool like `pyenv` or create a virtual environment with the correct Python version.

Warnings

• breaking Starting with version 0.5.2, the `udapy` CLI script transitioned to use `console_scripts` for invocation. While largely backward compatible, custom installations or environments that relied on specific `PATH` configurations might require verification.
  Fix: After installation, verify the `udapy` command is available by running `udapy -h`. If `command not found` occurs, ensure your `PATH` environment variable includes the directory where pip installs scripts (e.g., `~/.local/bin/`).
• gotcha Many advanced processing blocks (e.g., for parsing or dependency tree transformations) rely on the `ufal.udpipe` library. This is an optional dependency and is not installed by default with `pip install udapi`.
  Fix: If you need parsing or other `udpipe`-dependent functionality, install it explicitly: `pip install --upgrade ufal.udpipe`.
• gotcha UDAPI requires Python 3.9 or higher. Attempting to use it with older Python versions will result in runtime errors due to incompatible syntax or missing features.
  Fix: Ensure your Python environment is 3.9 or newer. It is recommended to use a virtual environment with the correct Python version.

Install

• pip install udapi Install latest version

Imports

• Document

  from udapi.core.document import Document

• Block

  from udapi.core.block import Block

• Conllu
  wrong:

  import Conllu

  correct:

  from udapi.block.read.conllu import Conllu

  Blocks are typically imported from `udapi.block.<category>.<BlockName>`.
• Text

  from udapi.block.read.text import Text

Quickstart

This quickstart demonstrates how to initialize a `Document`, read a plain text sentence using `read.Text`, tokenize it with `tokenize.Simple`, and then write the resulting (unparsed) document into CoNLL-U format using `write.Conllu`. The output is captured and printed.

import io
from contextlib import redirect_stdout

from udapi.core.document import Document
from udapi.block.read.text import Text
from udapi.block.tokenize.simple import Simple
from udapi.block.write.conllu import Conllu

# Create a new document
doc = Document()

# Read raw text into the document
read_text_block = Text(string="This is a test sentence.")
read_text_block.apply_on_document(doc)

# Tokenize the sentence using a simple whitespace tokenizer
tokenize_block = Simple()
tokenize_block.apply_on_document(doc)

# Write the document in CoNLL-U format to a string
f = io.StringIO()
with redirect_stdout(f):
    write_conllu_block = Conllu()
    write_conllu_block.apply_on_document(doc)
conllu_output = f.getvalue()

print(conllu_output)