fw-gear 0.3.5
Flywheel Gear Development Toolkit
Requires Python: ~=3.9

# fw-gear

**fw-gear** is a Python package maintained by [Flywheel](https://flywheel.io) that
simplifies the development of Flywheel gears. It provides a comprehensive toolkit for
interacting with gear runtime objects, managing inputs/outputs, and integrating with
the Flywheel platform.

> **Note:** The `fw-gear` package is the successor to the older
> `flywheel-gear-toolkit` package. New gear development should use `fw-gear`.

## Features

- **GearContext**: Context manager for gear lifecycle management
  - Access configuration values and input files
  - Manage output files and directories
  - Write metadata without SDK authentication
  - Configure logging
- **SDK Integration**: Automatic Flywheel SDK client instantiation when API key provided
- **Metadata Management**: Update container and file metadata via `.metadata.json`
- **Utilities**: Command execution, ZIP management, resource monitoring, and more
- **Nipype Integration**: Generate Nipype interfaces from gear manifests

## Installation

### Basic Installation

    pip install fw-gear

### With Optional Dependencies

Install specific extras for additional functionality:

    # Install with SDK support
    pip install fw-gear[sdk]

    # Install with all extras (SDK, Nipype, NumPy, psutil)
    pip install fw-gear[all]

**Available extras:**

- `sdk`: Flywheel SDK integration
- `nipype`: Nipype workflow integration
- `numpy`: NumPy array support
- `monitoring`: Resource monitoring with psutil
- `all`: All optional dependencies

## Quick Start

Create a simple gear in `run.py`:

    from fw_gear.context import GearContext

    def main(context):
        # Get configuration
        greeting = context.config.opts.get("greeting", "Hello")

        # Get input file
        input_file = context.config.get_input_path("input_file")

        # Write output
        with context.open_output("output.txt", "w") as f:
            f.write(f"{greeting} from {input_file}\n")

    if __name__ == "__main__":
        with GearContext() as context:
            context.init_logging()
            main(context)

## Documentation

Comprehensive documentation is available at:
[https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/](https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/)

- **[Getting Started][getting-started]** - Tutorial with practical examples
- **[GearContext Guide][gearcontext]** - Detailed usage guide
- **[Utils Module][utils]** - Helper utilities
- **[API Reference][api]** - Complete API documentation
- **[Migration Guide][migration]** - Migrating from flywheel-gear-toolkit

[getting-started]: https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/fw_gear/getting_started/
[gearcontext]: https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/fw_gear/context/
[utils]: https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/fw_gear/utils/
[api]: https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/fw_gear/reference/
[migration]: https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/fw_gear/migrate-guide/how_to_migrate/

## Contributing

We welcome contributions! Please see
[CONTRIBUTING.md](https://gitlab.com/flywheel-io/scientific-solutions/lib/fw-gear/-/blob/main/CONTRIBUTING.md)
for guidelines on contributing.

## License

`fw-gear` is released under the
[MIT License](https://gitlab.com/flywheel-io/scientific-solutions/lib/fw-gear/-/blob/main/LICENSE).

## Support

- **Documentation**: [https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/](https://flywheel-io.gitlab.io/scientific-solutions/lib/fw-gear/)
- **Issues**: [GitLab Issue Tracker](https://gitlab.com/flywheel-io/scientific-solutions/lib/fw-gear/-/issues)
- **Flywheel Docs**: [https://docs.flywheel.io/](https://docs.flywheel.io/)