✨ Release DeFFcode Stable v0.2.7

[abhiTronix]

Brief Description

New DeFFcode stable release is here with focus on bugfixes and maintenance updates 🎉

Requirements / Checklist

• I have read the DeFFcode PR Guidelines.
• I have read the DeFFcode Documentation.
• I have updated the documentation files accordingly(if required).

Related Issue

Context

DeFFcode's next stable release v0.2.7.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Miscellaneous (if available):

None

Summary by CodeRabbit

• New Features

  • Per-frame metadata extraction (frame, pts_time, keyframe info) and fast luma-only YUV decoding.

• Documentation

  • New recipes for metadata and YUV/grayscale workflows; Poetry install guide; many docs, navigation and asset-path updates; README/citation updates.

• Chores

  • Minimum Python now 3.10+; packaging moved to pyproject; CI/CD workflows and tooling modernized (linters/formatters updated); project version bumped to 0.2.7.

• Tests

  • Expanded coverage for luma/metadata behaviors and widespread test type annotations.

[codecov]

Codecov Report

❌ Patch coverage is 88.92617% with 33 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.18%. Comparing base (3df228b) to head (ded20e1).

Files with missing lines	Patch %	Lines
deffcode/ffdecoder.py	90.00%	15 Missing ⚠️
deffcode/sourcer.py	88.76%	10 Missing ⚠️
deffcode/ffhelper.py	82.60%	8 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (3df228b) and HEAD (ded20e1). Click for more details.

HEAD has 12 uploads less than BASE

Flag	BASE (3df228b)	HEAD (ded20e1)
	16	4

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #61      +/-   ##
==========================================
- Coverage   95.83%   86.18%   -9.66%     
==========================================
  Files           6        6              
  Lines         793      948     +155     
==========================================
+ Hits          760      817      +57     
- Misses         33      131      +98     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tests/test_ffhelper.py (1)

144-146: ⚠️ Potential issue | 🟡 Minor

Use logger.exception(...) instead of logger.exceptions(...).

Line 145 calls a non-existent logging.Logger method. In the timeout path, this raises AttributeError and masks the original timeout failure.

Proposed fix

-        elif isinstance(e, requests.exceptions.Timeout):
-            logger.exceptions(str(e))
+        elif isinstance(e, requests.exceptions.Timeout):
+            logger.exception(str(e))

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_ffhelper.py` around lines 144 - 146, The timeout-except branch in
tests/test_ffhelper.py is calling a non-existent method logger.exceptions and
should call logger.exception instead; update the except block that checks
isinstance(e, requests.exceptions.Timeout) to call logger.exception(str(e)) (or
logger.exception("timeout", exc_info=e)) so the original Timeout exception and
traceback are logged rather than raising an AttributeError from
logger.exceptions; reference the logger variable and the exception variable e in
that branch.

🧹 Nitpick comments (2)

docs/index.md (2)

26-26: Consider hyphenating the compound adjective.

The phrase "lightning fast video frames" uses a compound adjective. Standard grammar suggests hyphenating it as "lightning-fast" when it precedes the noun it modifies.

📝 Proposed grammar fix

-> A cross-platform **:fontawesome-solid-gauge-high: High-performance Video Frames Decoder** that flexibly executes FFmpeg pipeline inside a subprocess pipe for generating real-time, low-overhead, lightning fast video frames with robust error-handling in just a few lines of python code :fontawesome-solid-fire-flame-curved: 
+> A cross-platform **:fontawesome-solid-gauge-high: High-performance Video Frames Decoder** that flexibly executes FFmpeg pipeline inside a subprocess pipe for generating real-time, low-overhead, lightning-fast video frames with robust error-handling in just a few lines of python code :fontawesome-solid-fire-flame-curved: 

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/index.md` at line 26, The phrase "lightning fast video frames" in the
docs title should use a hyphenated compound adjective; update the text segment
"lightning fast video frames" to "lightning-fast video frames" in the string
containing "High-performance Video Frames Decoder ... lightning fast video
frames" so the compound adjective correctly precedes its noun.

---

200-212: Plan to update Zenodo citation when v0.2.7 is published.

The current DOI (10.5281/zenodo.12689394) correctly references v0.2.6, which is the latest version published to Zenodo. However, once this release is published to Zenodo as v0.2.7, the citation metadata in this file will need to be updated with the new DOI and version. Consider adding a comment or tracking this as a post-release task.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/index.md` around lines 200 - 212, Update the BibTeX entry that currently
contains DOI 10.5281/zenodo.12689394 and version v0.2.6 (entry key "deffcode" /
title "abhiTronix/deffcode: v0.2.6") once Zenodo publishes v0.2.7: replace the
doi field with the new DOI, update the version and title fields to v0.2.7, and
optionally add a small TODO comment above the BibTeX block noting this is a
post-release update to ensure the citation is kept in sync.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/CIlinux.yml:
- Around line 63-67: The workflow uses `sudo pip` and `sudo python` which
install into the system Python instead of the matrix-selected interpreter;
replace all usages of `sudo pip install -U ...` and `sudo python ...` with the
matrix interpreter’s pip by invoking `python -m pip install -U ...` (and `python
-m <module>` where appropriate) so the actions/setup-python selected version
(matrix) is used for installs and commands; update the lines that call `sudo pip
install -U numpy`, `sudo pip install -U .`, `sudo pip install -U
opencv-python-headless`, `sudo pip install -U vidgear[core]`, `sudo pip install
-U ruff six codecov pytest pytest-cov` and the later `sudo python` invocation to
use `python -m pip` / `python -m` respectively.

In `@docs/contribution/PR.md`:
- Around line 85-87: Replace the confusing artifact ``#!sh resolves `#123``` with
a plain issue-linking keyword example such as ``resolves `#123``` (or ``fixes
`#123```) in the commit guidance so the inline text is clear; update the line
containing the ``#!sh resolves `#123``` example to use the plain keyword example
instead.
- Line 81: The link uses the fragment "#testing-formatting-linting" which
markdownlint flags as invalid; fix it by adding an explicit HTML anchor/id
immediately before the "Testing & Linting" header (for example insert <a
name="testing-formatting-linting"></a> or <div
id="testing-formatting-linting"></div> directly above the "Testing & Linting"
header) so the existing link target resolves reliably across renderers.

---

Outside diff comments:
In `@tests/test_ffhelper.py`:
- Around line 144-146: The timeout-except branch in tests/test_ffhelper.py is
calling a non-existent method logger.exceptions and should call logger.exception
instead; update the except block that checks isinstance(e,
requests.exceptions.Timeout) to call logger.exception(str(e)) (or
logger.exception("timeout", exc_info=e)) so the original Timeout exception and
traceback are logged rather than raising an AttributeError from
logger.exceptions; reference the logger variable and the exception variable e in
that branch.

---

Nitpick comments:
In `@docs/index.md`:
- Line 26: The phrase "lightning fast video frames" in the docs title should use
a hyphenated compound adjective; update the text segment "lightning fast video
frames" to "lightning-fast video frames" in the string containing
"High-performance Video Frames Decoder ... lightning fast video frames" so the
compound adjective correctly precedes its noun.
- Around line 200-212: Update the BibTeX entry that currently contains DOI
10.5281/zenodo.12689394 and version v0.2.6 (entry key "deffcode" / title
"abhiTronix/deffcode: v0.2.6") once Zenodo publishes v0.2.7: replace the doi
field with the new DOI, update the version and title fields to v0.2.7, and
optionally add a small TODO comment above the BibTeX block noting this is a
post-release update to ensure the citation is kept in sync.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f7bc4974-5d58-48da-89b7-fb3f653f2825

📥 Commits

Reviewing files that changed from the base of the PR and between a29c5f8 and 0eabeaa.

📒 Files selected for processing (9)

• .github/workflows/CIlinux.yml
• README.md
• deffcode/ffhelper.py
• docs/contribution/PR.md
• docs/contribution/issue.md
• docs/index.md
• docs/recipes/advanced/transcode-hw-acceleration.md
• pyproject.toml
• tests/test_ffhelper.py

✅ Files skipped from review due to trivial changes (2)

• README.md
• pyproject.toml

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/recipes/advanced/transcode-hw-acceleration.md
• deffcode/ffhelper.py

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/installation/index.md`:
- Line 42: The sentence referencing Python support is awkwardly worded; replace
the phrase ":fontawesome-brands-python: [**Python
3.10+**](https://www.python.org/downloads/) are only supported legacies for
installing DeFFcode `v0.2.7` and above." with a clear line such as "Python 3.10+
is the only supported Python version for DeFFcode v0.2.7 and newer." Keep the
reference to the Python download link and the `v0.2.7` version string so readers
can locate the change using the "Python 3.10+" token and the `v0.2.7`
identifier.
- Around line 184-187: Convert the fenced triple-backtick shell code blocks that
contain the "poetry add deffcode" snippet and the subsequent "git clone ... /
poetry install" snippet into indented code blocks to satisfy markdownlint MD046;
locate the fenced blocks (the ones starting with ```sh and containing the lines
"# Add latest stable release as a project dependency / poetry add deffcode" and
the later block with "# clone the repository and get inside / git clone ... &&
cd deffcode" and replace each fenced block with four-space-indented lines
preserving the exact shell commands and blank lines.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b31eeb7a-0139-4523-9924-1e1c39617d6a

📥 Commits

Reviewing files that changed from the base of the PR and between 0eabeaa and 88e1cbc.

📒 Files selected for processing (4)

• .github/workflows/CIlinux.yml
• docs/installation/index.md
• mkdocs.yml
• pyproject.toml

✅ Files skipped from review due to trivial changes (2)

• pyproject.toml
• .github/workflows/CIlinux.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• mkdocs.yml

[coderabbitai]

♻️ Duplicate comments (1)

.github/workflows/CIlinux.yml (1)

63-67: ⚠️ Potential issue | 🟠 Major

Use the matrix interpreter consistently and harden the pytest exit-code logic.

Line 63–67 and Line 74 still run through sudo, which can bypass the actions/setup-python interpreter and invalidate the 3.10–3.13 matrix. Also, on Line 74, $code can be unset when pytest exits 0, making the numeric check brittle.

Suggested patch

       - name: Install Pip Dependencies
         run: |
-          sudo pip install -U numpy
-          sudo pip install -U .
-          sudo pip install -U opencv-python-headless 
-          sudo pip install -U vidgear[core]
-          sudo pip install -U ruff six codecov pytest pytest-cov
+          python -m pip install -U pip
+          python -m pip install -U numpy
+          python -m pip install -U .
+          python -m pip install -U opencv-python-headless
+          python -m pip install -U vidgear[core]
+          python -m pip install -U ruff six codecov pytest pytest-cov
         if: success()
@@
       - name: Run pytest and ruff
         run: |
-          timeout 1200 sudo pytest -sv --cov=deffcode --cov-report=xml --cov-report term-missing tests/ || code=$?; if [[ $code -ne 124 && $code -ne 0 ]]; then exit $code; else echo "EXIT_CODE=$code" >>$GITHUB_ENV; fi
-          ruff check .
-          ruff format --check .
+          code=0
+          timeout 1200 python -m pytest -sv --cov=deffcode --cov-report=xml --cov-report term-missing tests/ || code=$?
+          if [[ $code -ne 124 && $code -ne 0 ]]; then exit "$code"; fi
+          echo "EXIT_CODE=$code" >> "$GITHUB_ENV"
+          python -m ruff check .
+          python -m ruff format --check .
         if: success()

#!/bin/bash
set -euo pipefail

echo "== configured runner interpreter =="
command -v python
python -V
command -v pip
pip -V

echo "== interpreter/pip under sudo (should differ if misconfigured) =="
sudo bash -lc 'command -v python; python -V; command -v pip; pip -V'

echo "== reproduce unset-code branch behavior =="
bash -lc 'unset code; if [[ $code -ne 124 && $code -ne 0 ]]; then echo fail; else echo pass; fi' || true

Also applies to: 74-76

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/CIlinux.yml around lines 63 - 67, Replace the sudo pip
installs with interpreter-bound installs so the matrix-controlled Python is used
(use python -m pip or the runner's pip instead of sudo) — update the pip install
commands that currently use sudo (the
numpy/opencv/vidgear/ruff/six/codecov/pytest lines) to run under the configured
interpreter from actions/setup-python; also harden the pytest exit-code logic by
ensuring the variable used for the check is always defined and compared
numerically (use a default like ${code:-0} or explicitly set code after pytest)
and change the conditional that checks code (the branch that inspects $code for
124/0) to handle an unset value safely and compare as integers.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In @.github/workflows/CIlinux.yml:
- Around line 63-67: Replace the sudo pip installs with interpreter-bound
installs so the matrix-controlled Python is used (use python -m pip or the
runner's pip instead of sudo) — update the pip install commands that currently
use sudo (the numpy/opencv/vidgear/ruff/six/codecov/pytest lines) to run under
the configured interpreter from actions/setup-python; also harden the pytest
exit-code logic by ensuring the variable used for the check is always defined
and compared numerically (use a default like ${code:-0} or explicitly set code
after pytest) and change the conditional that checks code (the branch that
inspects $code for 124/0) to handle an unset value safely and compare as
integers.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2855d88f-5802-4052-9820-df5485a65f8e

📥 Commits

Reviewing files that changed from the base of the PR and between 0778d57 and e93be51.

📒 Files selected for processing (1)

• .github/workflows/CIlinux.yml