{"id":8429,"library":"ploomber-core","title":"Ploomber Core","description":"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.","status":"active","version":"0.2.27","language":"en","source_language":"en","source_url":"https://github.com/ploomber/core","tags":["data-pipelines","workflow-management","utilities","data-science","core-library"],"install":[{"cmd":"pip install ploomber-core","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Telemetry","correct":"from ploomber_core.telemetry import Telemetry"},{"symbol":"deprecated","correct":"import ploomber_core.deprecated"},{"symbol":"exceptions","correct":"import ploomber_core.exceptions"},{"symbol":"validations","correct":"import ploomber_core.validations"}],"quickstart":{"code":"import os\nfrom ploomber_core.telemetry import Telemetry\n\n# Initialize Telemetry. In a real application, this is often managed by Ploomber's main library.\n# The 'do_not_track' setting can be controlled via an environment variable.\ntelemetry = Telemetry(\n    config={'do_not_track': os.environ.get('PLOOMBER_DO_NOT_TRACK', '0') == '1'},\n    version='0.2.27' # Typically, this would be `__version__` from the package\n)\n\nprint(f\"Ploomber-core Telemetry initialized (version {telemetry.version}).\")\nprint(f\"Telemetry tracking enabled: {not telemetry.do_not_track}\")\n\n# Example: In a larger application, you might log events:\n# telemetry.log_api_call('some_internal_function')","lang":"python","description":"Demonstrates importing a core utility from ploomber-core and initializing its telemetry component, showing how to respect the `PLOOMBER_DO_NOT_TRACK` environment variable."},"warnings":[{"fix":"Wrap your script's main execution logic (especially when using `dag.build()` or `ploomber build` from a script) within `if __name__ == '__main__':`.","message":"When 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__':`.","severity":"gotcha","affected_versions":"All versions on macOS/Windows"},{"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.","message":"Ploomber 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.","severity":"gotcha","affected_versions":"All versions of Ploomber and ploomber-core"},{"fix":"Monitor `FutureWarning` messages during development and consult the changelog before upgrading to new major versions to adapt to API changes.","message":"The 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.","severity":"breaking","affected_versions":"Major version increments (e.g., 0.X to 0.Y)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Encapsulate the main execution block of your script within `if __name__ == '__main__':` to properly initialize child processes.","cause":"Running Ploomber tasks (specifically `ploomber.tasks.PythonCallable`) from a script on macOS or Windows without the `if __name__ == '__main__':` guard, leading to multiprocessing issues.","error":"An attempt has been made to start a new process before the current process has finished its bootstrapping phase."},{"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.","cause":"Unverified data assumptions or faulty logic in an upstream task allows bad data to propagate, causing a seemingly unrelated failure in a later task.","error":"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)."},{"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.","cause":"An older or incompatible version of `ploomber-core` is present or being installed, conflicting with the requirements of the main `ploomber` package.","error":"Incompatibility with ploomber-core when running 'pip install ploomber' or 'ploomber install'."}]}