Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,4 @@ lcov_html_report/
.coverage.*
coverage.xml
coverage_html_report/
.ruff_cache/
10 changes: 7 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,12 @@ Here are the two possible CLAs:

## Coding Conventions

Python style continues to be checked with Flake8 using the existing rules in
`setup.cfg`. Initialize submodules, run `uv sync --locked`, then `make lint`
and `make test`. C++ continues to use the existing clang-format configuration.
Python style is checked with Ruff, configured in `pyproject.toml`. Use double
quotes and omit trailing commas from list literals. Run `uv sync --locked` after
initializing submodules, then `make lint` and `make format-check`. `make format-python` runs
Ruff's formatter followed by lint autofixes and list-comma cleanup; the order is
important because the formatter introduces commas that the final cleanup removes.
C++ continues to use the existing clang-format configuration.

The default uv development group includes lint and test tools. Documentation
uses `uv sync --locked --group docs` (Python 3.11+). Commit `uv.lock` when changing
Expand Down Expand Up @@ -89,6 +92,7 @@ Once you are happy with your change, you can verify that the change didn't cause
```bash
make test
make lint
make format-check
```

If all the tests pass and you'd like to send your change in for consideration, push it to your remote repo:
Expand Down
14 changes: 11 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.PHONY: sync coverage test test-core test_first_fail clean lint doc-html python-version wheel sdist build lcov lcov-html lcov-reset
.PHONY: sync coverage test test-core test_first_fail clean lint format-python \
format-check doc-html python-version wheel sdist build lcov lcov-html lcov-reset

# Special definition to handle Make from stripping newlines
define newline
Expand Down Expand Up @@ -41,7 +42,7 @@ test-core: python-version

# CI
###################################
ci-prebuild: lint
ci-prebuild: lint format-check
ci-postbuild: coverage
###################################

Expand Down Expand Up @@ -100,7 +101,14 @@ sync:
@$(UV) sync --locked

lint:
@$(UV) run --locked --only-group lint python -m flake8
@$(UV) run --locked --only-group lint ruff check .

# Check the final formatter + autofix result without editing the working tree.
format-check:
@$(UV) run --locked --only-group lint python maintainers/format_python.py --check

format-python:
@$(UV) run --locked --only-group lint python maintainers/format_python.py

# Build a source distribution, then build the wheel from that archive.
build:
Expand Down
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ the development environment and compile the native extensions:
```sh
uv sync --locked
uv run python -m unittest discover -s tests
make lint
uv run ruff check .
```

The package supports Python 3.9–3.15. `uv.lock` pins development dependencies
Expand All @@ -169,8 +169,11 @@ Use `uv sync --locked --group docs` to install documentation tools (Python 3.11+
No environment activation is needed with `uv run`.

The Makefile provides the same commands as `make sync`, `make test`, `make lint`,
and `make coverage`. Python style continues to be checked with Flake8; the
existing `make format` target formats C++.
`make format-check`, and `make coverage`. Run `make format-python` to apply Ruff's
formatting pipeline: `ruff format` followed by lint autofixes for double quotes,
import sorting, and removal of trailing commas from list literals. `make format-check`
checks that combined result without editing files. The existing `make format`
target formats C++.

`uv build` creates a source distribution and builds a wheel from that archive.
The build backend is scikit-build-core, which invokes the existing CMake build.
Expand Down
74 changes: 31 additions & 43 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,83 +3,81 @@
# Copyright Contributors to the OpenTimelineIO project
import re

import sphinx_rtd_theme
import opentimelineio

# -- Project information ---------------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'OpenTimelineIO'
project = "OpenTimelineIO"
copyright = "Copyright Contributors to the OpenTimelineIO project"
author = 'Contributors to the OpenTimelineIO project'
author = "Contributors to the OpenTimelineIO project"

try:
RELEASE = opentimelineio.__version__
except AttributeError:
RELEASE = 'unknown'
RELEASE = "unknown"

# The short X.Y version.
version = RELEASE.split('-')[0]
version = RELEASE.split("-")[0]
# The full version, including alpha/beta/rc tags.
release = RELEASE

# -- General configuration -------------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.intersphinx',
'myst_parser', # This plugin is used to format our markdown correctly
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.intersphinx",
"myst_parser" # This plugin is used to format our markdown correctly
]

templates_path = ['_templates']
templates_path = ["_templates"]

exclude_patterns = ['_build', '_templates', '.venv']
exclude_patterns = ["_build", "_templates", ".venv"]

pygments_style = 'sphinx'
pygments_style = "sphinx"


# -- Options for HTML output -----------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "sphinx_rtd_theme"

htmlhelp_basename = f'{project.lower()}doc'
htmlhelp_basename = f"{project.lower()}doc"


# -- Options for LaTeX output ----------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output

latex_documents = [
('index', f'{project.lower()}.tex',
f'{project} Documentation',
author, 'manual'),
("index", f"{project.lower()}.tex", f"{project} Documentation", author, "manual")
]

# -- Options for manual page output ----------------------------------------------------
# sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output

man_pages = [
('index', project.lower(), f'{project} Documentation',
[author], 1)
]
man_pages = [("index", project.lower(), f"{project} Documentation", [author], 1)]

# -- Options for Texinfo output --------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-texinfo-output

texinfo_documents = [
('index', project.lower(), f'{project} Documentation',
author, project, 'One line description of project.',
'Miscellaneous'),
(
"index",
project.lower(),
f"{project} Documentation",
author,
project,
"One line description of project.",
"Miscellaneous",
)
]

# -- Options for intersphinx -----------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration

intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
}
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

# -- Options for Autodoc ---------------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
Expand All @@ -88,22 +86,16 @@
# Pybind11 generates class signatures on the __init__ method.
autoclass_content = "both"

autodoc_default_options = {
'undoc-members': True
}
autodoc_default_options = {"undoc-members": True}

# -- Options for linkcheck -------------------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder

linkcheck_exclude_documents = [
r'cxx/cxx'
]
linkcheck_exclude_documents = [r"cxx/cxx"]

# These URLs give 403 Forbidden to the linkcheck bot (bot/user-agent filtering)
# even though they work fine in a browser.
linkcheck_ignore = [
r'https://opensource.org/licenses/MIT',
]
linkcheck_ignore = [r"https://opensource.org/licenses/MIT"]

# -- Options for MySt-Parser -----------------------------------------------------------
# https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html
Expand All @@ -112,6 +104,7 @@

# -- Custom ----------------------------------------------------------------------------


def process_signature(
app,
what: str,
Expand Down Expand Up @@ -149,7 +142,7 @@ def process_signature(
nameToMatch = name.split(".")[-1] if not isClass else "__init__"

# Maybe get use sphinx.util.inspect.signature_from_str ?
if match := re.search(fr"^\d+\.\s{nameToMatch}(\(.*)", line):
if match := re.search(rf"^\d+\.\s{nameToMatch}(\(.*)", line):
signatures.append(match.group(1))
elif signature:
signatures.append(signature)
Expand All @@ -170,12 +163,7 @@ def process_signature(


def process_docstring(
app,
what: str,
name: str,
obj: object,
options: dict[str, str],
lines: list[str],
app, what: str, name: str, obj: object, options: dict[str, str], lines: list[str]
):
for index, line in enumerate(lines):
# Remove "self" from docstrings of overloaded functions/methods.
Expand All @@ -188,7 +176,7 @@ def process_docstring(
#
# "self" is a distraction that can be removed to improve readability.
# This should be removed once https://github.com/pybind/pybind11/pull/2621 is merged.
if re.match(fr'\d+\. {name.split("."[0])}', line):
if re.match(rf"\d+\. {name.split('.'[0])}", line):
line = re.sub(r"self\: [a-zA-Z0-9._]+(,\s)?", "", line)
lines[index] = line

Expand Down
7 changes: 5 additions & 2 deletions docs/tutorials/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and run:
```sh
uv sync --locked
uv run python -m unittest discover -s tests
make lint
uv run ruff check .
```

This builds the native bindings and installs the package in editable mode,
Expand All @@ -83,7 +83,10 @@ available. After changing C++, rebuild with:
uv sync --locked --reinstall-package opentimelineio
```

`uv build` creates an sdist
`make format-python` runs Ruff formatting followed by quote, comma, and import
autofixes. `make format-check` checks that combined result without editing files.
Use these commands rather than running the formatter alone, since the final
comma fix is part of the project's style. `uv build` creates an sdist
and then builds a wheel from it. `uv sync --locked --group docs` installs the
documentation tools, which require Python 3.11 or newer.

Expand Down
47 changes: 18 additions & 29 deletions examples/conform.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,38 +25,32 @@
"""

import argparse
from argparse import RawTextHelpFormatter
import glob
import os
from argparse import RawTextHelpFormatter

import opentimelineio as otio


def parse_args():
""" parse arguments out of sys.argv """
parser = argparse.ArgumentParser(description=__doc__,
formatter_class=RawTextHelpFormatter)
"""parse arguments out of sys.argv"""
parser = argparse.ArgumentParser(
description=__doc__, formatter_class=RawTextHelpFormatter
)
parser.add_argument(
'-i',
'--input',
"-i",
"--input",
type=str,
required=True,
help='Timeline file to read. Supported formats: {adapters}'
''.format(adapters=otio.adapters.available_adapter_names())
help="Timeline file to read. Supported formats: {adapters}".format(
adapters=otio.adapters.available_adapter_names()
),
)
parser.add_argument(
'-f',
'--folder',
type=str,
required=True,
help='Folder to look for media in.'
"-f", "--folder", type=str, required=True, help="Folder to look for media in."
)
parser.add_argument(
'-o',
'--output',
type=str,
required=True,
help="Timeline file to write out."
"-o", "--output", type=str, required=True, help="Timeline file to write out."
)
return parser.parse_args()

Expand All @@ -83,16 +77,14 @@ def _find_matching_media(name, folder):
else:
print(
"WARNING: {} matches found for clip '{}', using '{}'".format(
len(matches),
name,
matches[0]
len(matches), name, matches[0]
)
)
return matches[0]


def _conform_timeline(timeline, folder):
""" Look for replacement media for each clip in the given timeline.
"""Look for replacement media for each clip in the given timeline.

The clips are relinked in place if media with a matching name is found.
"""
Expand All @@ -110,8 +102,8 @@ def _conform_timeline(timeline, folder):
# relink to the found path
clip.media_reference = otio.schema.ExternalReference(
target_url="file://" + new_path,
available_range=None # the available range is unknown without
# opening the file
available_range=None, # the available range is unknown without
# opening the file
)
count += 1

Expand All @@ -126,12 +118,9 @@ def main():
print(f"Relinked {count} clips to new media.")
otio.adapters.write_to_file(timeline, args.output)
print(
"Saved {} with {} clips.".format(
args.output,
len(list(timeline.find_clips()))
)
"Saved {} with {} clips.".format(args.output, len(list(timeline.find_clips())))
)


if __name__ == '__main__':
if __name__ == "__main__":
main()
Loading