{"id":3803,"library":"shrub-py","title":"Shrub.py","description":"Shrub.py is a Python library designed for programmatically building Evergreen project configurations. It allows users to define complex CI/CD task graphs and build variants using Python objects, which can then be serialized into the JSON format required by Evergreen. The library is actively maintained, with its latest version being 3.10.0, released in April 2025.","status":"active","version":"3.10.0","language":"en","source_language":"en","source_url":"https://github.com/evergreen-ci/shrub.py","tags":["configuration","evergreen","ci/cd","automation","build system"],"install":[{"cmd":"pip install shrub-py","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.8.1 or newer.","package":"python","optional":false}],"imports":[{"note":"The library's API is versioned under the `shrub.vX` namespace. Always import from the specific major version (e.g., `v3`) to ensure compatibility with the desired Evergreen API version.","wrong":"from shrub.evg_task import EvgTask","symbol":"EvgTask","correct":"from shrub.v3.evg_task import EvgTask"},{"note":"Similar to other components, `ShrubService` is part of the versioned API. Ensure you import from the correct `vX` namespace.","wrong":"from shrub.shrub_service import ShrubService","symbol":"ShrubService","correct":"from shrub.v3.shrub_service import ShrubService"}],"quickstart":{"code":"from shrub.v3.evg_task import EvgTask, EvgTaskDependency\nfrom shrub.v3.evg_build_variant import BuildVariant, DisplayTask\nfrom shrub.v3.evg_command import FunctionCall\nfrom shrub.v3.evg_project import EvgProject\nfrom shrub.v3.shrub_service import ShrubService\nimport json\n\nn_tasks = 3\n\ndef define_task(index):\n    name = f\"my_test_task_{index}\"\n    return EvgTask(\n        name=name,\n        commands=[\n            FunctionCall(func=\"do_setup_function\"),\n            FunctionCall(\n                func=\"run_test_script\",\n                vars={\n                    \"param1\": f\"value_{index}\",\n                    \"param2\": \"static_value\"\n                }\n            ),\n            FunctionCall(func=\"do_teardown_function\")\n        ],\n        depends_on=[EvgTaskDependency(name=\"compile_job\")]\n    )\n\ntasks = [define_task(i) for i in range(n_tasks)]\ndisplay_task = DisplayTask(\n    name=\"full_test_suite\",\n    execution_tasks=[t.name for t in tasks]\n)\n\nvariant = BuildVariant(\n    name=\"linux-build\",\n    tasks=[],\n    display_tasks=[display_task]\n)\n\nproject = EvgProject(buildvariants=[variant], tasks=tasks)\n\n# Generate the Evergreen JSON configuration\nevergreen_config_json = ShrubService.generate_json(project)\n\nprint(json.dumps(evergreen_config_json, indent=4))\n","lang":"python","description":"This quickstart demonstrates how to define an Evergreen project configuration using shrub.py. It creates multiple parallel tasks, groups them under a display task, associates them with a build variant, and then generates the corresponding Evergreen JSON output. This example illustrates task definition, command execution with variables, and task dependencies."},"warnings":[{"fix":"Review the official `shrub.py` documentation and release notes for breaking changes and update import paths (e.g., `from shrub.v2...` to `from shrub.v3...`) and object constructors accordingly.","message":"Shrub.py uses versioned import paths (e.g., `shrub.v3`). Upgrading to a new major version of the library may require updating import statements to reflect the new API version (e.g., from `shrub.v2` to `shrub.v3`).","severity":"breaking","affected_versions":"<3.0.0 (hypothetical, as `v3` is current)"},{"fix":"Always consult the official Evergreen documentation for the precise structure and valid values for project configurations, tasks, and commands when encountering issues with the generated JSON.","message":"The structure and available fields for Evergreen configurations are dictated by the Evergreen API itself. Errors in generated JSON often stem from mismatches with the expected Evergreen schema, rather than `shrub.py` library issues.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}