# Migrating to `ionworks`

`ionworks` replaces `ionworks-api`, `ionworksdata`, `ionworks-schema` and `iwutil`.
Those four packages receive no further releases.

| Before | After |
|---|---|
| `pip install ionworks-api ionworksdata ionworks-schema iwutil` | `pip install ionworks` |
| `from ionworks import Ionworks` | `import ionworks as iw`; `iw.api.Client()` |
| `import ionworks as iw`; `iw.Ionworks()` | `iw.api.Client()` |
| `from ionworks.<module> import X` | `from ionworks.api.<module> import X` |
| `from ionworks.client import Ionworks`; `mock.patch("ionworks.Ionworks")` | `from ionworks.api import Client`; `mock.patch("ionworks.api.Client")` |
| `import ionworksdata as iwdata` | `import ionworks as iw`; `iw.data` |
| `import ionworks_schema as iws` | `import ionworks as iw`; `iw.pipeline` |
| `import iwutil` | `import ionworks as iw`; `iw.util` |
| `from ionworks.pipeline import PipelineClient` | `from ionworks.api.pipeline import PipelineClient` |

Every module and name inside an old package kept its path in the new subpackage,
so `ionworksdata.transform.set_cycle_count` is
`ionworks.data.transform.set_cycle_count`.

`ionworks.pipeline` now names the pipeline-building subpackage (formerly
`ionworks_schema`). The client module that `ionworks-api` shipped as
`ionworks.pipeline` (`PipelineClient`, reached as `client.pipeline`) is now
`ionworks.api.pipeline`, by the same rule as every other client module.

`ionworks` and `ionworks-api` both install a top-level `ionworks` package, so they
cannot share an environment, and `import ionworks` raises an error when it finds
both. Install `ionworks` into a fresh environment, or replace the old packages in
place with `pip uninstall ionworks-api ionworksdata && pip install --force-reinstall ionworks`.
The final `ionworks-api`, 0.41.0, raises the same error. An older `ionworks-api`
installed after `ionworks` overwrites that check, so the import fails without the
message; the same commands fix it.

`ionworkspipeline` releases before 0.48.0 require `ionworksdata` and
`ionworks-schema`, so they cannot share an environment with `ionworks`. Upgrade
`ionworkspipeline` to 0.48.0 or later, which depends on `ionworks`.

Objects pickled under the old packages do not load under `ionworks`, because each
class now reports its new module path.

## Let your coding agent do it

The Ionworks skills include `migrate-to-ionworks`, which finds every old import,
patch target and dependency in a project, rewrites them, rebuilds the environment,
runs your code, and reports anything it could not map. Install the skills with
`ionworks skills install` (the command ships with both `ionworks-api` and
`ionworks`; see [Bring your own agent](https://docs.ionworks.com/agents#bring-your-own-agent)),
then ask your agent to use the `migrate-to-ionworks` skill on your project.