ploomber-core

library0.2.27pypypi✓ verified 85d ago

Ploomber-core is a foundational Python library providing common utilities and functionality reused across projects within the Ploomber ecosystem. It includes modules for deprecations, telemetry, exceptions, and validations. As a core component, it supports the main Ploomber library, which is a framework for building modular data pipelines, integrating with Jupyter, and deploying to various platforms like Airflow and Kubernetes. The library is actively maintained, with a current version of 0.2.27, and the broader Ploomber project follows semantic versioning with frequent minor releases.

devops data

pip install ploomber-core

package ↗homepage ↗

INSTALL

IMPORT

SIG · PLOOMBER-CORE

ploomber-core

devopspythonv0.2.27

Install

2.7s avg

Import

974ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.27 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.025s · 26.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.7s · import 0.924s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Telemetry

✓ from ploomber_core.telemetry import Telemetry

deprecated

✓ import ploomber_core.deprecated

exceptions

✓ import ploomber_core.exceptions

validations

✓ import ploomber_core.validations

Demonstrates importing a core utility from ploomber-core and initializing its telemetry component, showing how to respect the `PLOOMBER_DO_NOT_TRACK` environment variable.

import os from ploomber_core.telemetry import Telemetry # Initialize Telemetry. In a real application, this is often managed by Ploomber's main library. # The 'do_not_track' setting can be controlled via an environment variable. telemetry = Telemetry( config={'do_not_track': os.environ.get('PLOOMBER_DO_NOT_TRACK', '0') == '1'}, version='0.2.27' # Typically, this would be `__version__` from the package ) print(f"Ploomber-core Telemetry initialized (version {telemetry.version}).") print(f"Telemetry tracking enabled: {not telemetry.do_not_track}") # Example: In a larger application, you might log events: # telemetry.log_api_call('some_internal_function')

Debug

Known issues

gotchaWhen running PythonCallable tasks (from the main Ploomber library, which uses ploomber-core) in a script on macOS or Windows, multiprocessing issues can arise if the task execution isn't protected by `if __name__ == '__main__':`.

fix

Wrap your script's main execution logic (especially when using `dag.build()` or `ploomber build` from a script) within `if __name__ == '__main__':`.

affects: All versions on macOS/Windows

gotchaPloomber tasks (relying on ploomber-core's foundations) are designed to produce at least one output (a 'product', e.g., a file or database entry) to enable incremental builds and dependency tracking. Tasks that generate no explicit output can break pipeline logic or prevent caching benefits.

fix

Ensure each task generates at least one product. If a task truly has no direct output, consider merging its logic with an upstream task that does produce output, or use the `on_finish` hook for side effects that don't need tracking.

affects: All versions of Ploomber and ploomber-core

breakingThe main Ploomber library (which depends on ploomber-core) follows semantic versioning, meaning major version increments (`0.x` to `0.y`) can introduce API-incompatible changes. These are typically preceded by `FutureWarning` for two minor releases.

fix

Monitor `FutureWarning` messages during development and consult the changelog before upgrading to new major versions to adapt to API changes.

affects: Major version increments (e.g., 0.X to 0.Y)

Errors

Common errors & fixes

An attempt has been made to start a new process before the current process has finished its bootstrapping phase.

Running Ploomber tasks (specifically `ploomber.tasks.PythonCallable`) from a script on macOS or Windows without the `if __name__ == '__main__':` guard, leading to multiprocessing issues.

fix

Encapsulate the main execution block of your script within `if __name__ == '__main__':` to properly initialize child processes.

Pipeline build failed due to an error in a downstream task, but the root cause is difficult to trace to an upstream data quality issue (e.g., unexpected nulls, incorrect join cardinality).

Unverified data assumptions or faulty logic in an upstream task allows bad data to propagate, causing a seemingly unrelated failure in a later task.

fix

Implement robust pipeline testing using Ploomber's `on_finish` hooks to validate data quality and expectations immediately after each task execution. This catches issues closer to their source.

Incompatibility with ploomber-core when running 'pip install ploomber' or 'ploomber install'.

An older or incompatible version of `ploomber-core` is present or being installed, conflicting with the requirements of the main `ploomber` package.

fix

Ensure `ploomber-core` is updated to a version compatible with your `ploomber` installation. Use `pip install --upgrade ploomber ploomber-core` or consult the `ploomber` changelog for specific version requirements.

Upgrade

Version history

0.2.27latest on PyPI · released Jul 21, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/ploomber-core/ ↗

homepagehttps://ploomber.io ↗