.. _pygeai_gam_migration:

===================================
Migrating to pygeai-gam Package
===================================

.. warning::
   The ``pygeai.gam`` module has been **deprecated** and moved to a standalone package.
   Starting with pygeai 0.7.0, you must migrate to the new ``pygeai-gam`` package.

Overview
========

The gam functionality for managing GeneXus Access Manager (GAM) OAuth has been extracted from the main ``pygeai`` package 
into a dedicated ``pygeai-gam`` package. This change provides better separation of concerns and allows 
the gam functionality to evolve independently.

What Changed
============

Package Split
-------------

.. list-table::
   :header-rows: 1
   :widths: 30 35 35

   * - Component
     - Before (pygeai ≤0.6.x)
     - After (pygeai ≥0.7.0)
   * - Import path
     - ``from pygeai.gam import ...``
     - ``from pygeai_gam import ...``
   * - Package name
     - ``pygeai`` (bundled)
     - ``pygeai-gam`` (separate)
   * - Installation
     - ``pip install pygeai``
     - ``pip install pygeai-gam``
   * - CLI command
     - ``geai-gam`` (from pygeai)
     - ``geai-gam`` (from pygeai-gam)

Import Changes
--------------

All imports need to be updated:

.. code-block:: python
   :caption: Before (deprecated)

   from pygeai.gam.clients import GAMClient
   from pygeai.gam.endpoints import GAM_ENDPOINTS
   from pygeai.gam import PKCEHelper

.. code-block:: python
   :caption: After (new)

   from pygeai_gam import GAMClient
   from pygeai_gam.endpoints import GAM_ENDPOINTS
   from pygeai_gam import PKCEHelper

Migration Guide
===============

Step 1: Install pygeai-gam
-----------------------------

Install the new package (this will automatically install pygeai as a dependency):

.. code-block:: bash

   pip install pygeai-gam

.. note::
   If you're upgrading from pygeai ≤0.6.x, you can keep using your existing pygeai
   installation or upgrade it:

   .. code-block:: bash

      pip install --upgrade pygeai pygeai-gam

Step 2: Run the Migration Script (Recommended)
-----------------------------------------------

The easiest way to migrate your code is to use the automated migration script:

.. code-block:: bash

   # Dry run to preview changes
   migrate-pygeai-gam /path/to/your/project --dry-run --verbose

   # Apply changes with backups
   migrate-pygeai-gam /path/to/your/project --backup

   # Apply changes without backups
   migrate-pygeai-gam /path/to/your/project --no-backup

Migration Script Options
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: text

   usage: migrate-pygeai-gam [-h] [--dry-run] [--backup] [--no-backup] 
                               [--verbose] directory

   Migrate code from pygeai.gam to pygeai_gam

   positional arguments:
     directory      Directory containing Python files to migrate

   options:
     -h, --help     Show this help message
     --dry-run      Show what would be changed without modifying files
     --backup       Create backup files (.py.bak) before modifying (default)
     --no-backup    Do not create backup files
     --verbose, -v  Show detailed information about changes

Examples
^^^^^^^^

**Preview changes before applying:**

.. code-block:: bash

   migrate-pygeai-gam . --dry-run

**Migrate current directory with backups:**

.. code-block:: bash

   migrate-pygeai-gam . --backup

**Migrate without creating backups:**

.. code-block:: bash

   migrate-pygeai-gam /path/to/project --no-backup

**Show detailed diff of changes:**

.. code-block:: bash

   migrate-pygeai-gam . --dry-run --verbose

Step 3: Manual Migration (Alternative)
---------------------------------------

If you prefer to migrate manually, update all imports:

Using Find & Replace in Your Editor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. **Find:** ``from pygeai.gam``  
   **Replace with:** ``from pygeai_gam``

2. **Find:** ``import pygeai.gam``  
   **Replace with:** ``import pygeai_gam``

Using Command Line (Linux/macOS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   # Update all Python files in current directory and subdirectories
   find . -name "*.py" -type f -exec sed -i '' \
     's/from pygeai\.gam/from pygeai_gam/g; s/import pygeai\.gam/import pygeai_gam/g' {} \;

.. warning::
   Always create backups before running bulk find-replace operations!

Step 4: Update Dependencies
----------------------------

Update your project's dependencies:

**requirements.txt:**

.. code-block:: text
   :caption: Before

   pygeai>=0.7.0

.. code-block:: text
   :caption: After

   pygeai>=0.7.0
   pygeai-gam>=0.1.0

**pyproject.toml:**

.. code-block:: toml
   :caption: Before

   [project]
   dependencies = [
       "pygeai>=0.6.0"
   ]

.. code-block:: toml
   :caption: After

   [project]
   dependencies = [
       "pygeai>=0.7.0",
       "pygeai-gam>=0.1.0"
   ]

**setup.py:**

.. code-block:: python
   :caption: Before

   install_requires=[
       "pygeai>=0.6.0"
   ]

.. code-block:: python
   :caption: After

   install_requires=[
       "pygeai>=0.7.0",
       "pygeai-gam>=0.1.0"
   ]

Step 5: Test Your Application
------------------------------

After migration, test your application thoroughly:

.. code-block:: bash

   # Run your tests
   pytest

   # Try importing the new package
   python -c "from pygeai_gam.clients import GAMClient; print('✓ Import successful')"

   # Test the CLI
   gam-cli --help

Step 6: Clean Up (Optional)
----------------------------

Remove backup files created by the migration script:

.. code-block:: bash

   # Preview backup files
   find . -name "*.py.bak"

   # Remove backup files
   find . -name "*.py.bak" -delete

Common Issues and Solutions
============================

ImportError: No module named 'pygeai_gam'
--------------------------------------------

**Problem:** You haven't installed the new package yet.

**Solution:**

.. code-block:: bash

   pip install pygeai-gam

DeprecationWarning: The 'pygeai.gam' module is deprecated
------------------------------------------------------------

**Problem:** You're still importing from the old ``pygeai.gam`` module.

**Solution:** Run the migration script or manually update your imports:

.. code-block:: bash

   migrate-pygeai-gam /path/to/project

CLI command 'gam-cli' not found after migration
-------------------------------------------------

**Problem:** The ``gam-cli`` command was removed from pygeai.

**Solution:** Install ``pygeai-gam`` to get the command:

.. code-block:: bash

   pip install pygeai-gam

Tests failing after migration
------------------------------

**Problem:** Test imports or configurations might need updating.

**Solution:**

1. Update test imports:

   .. code-block:: python

      # Before
      from pygeai.gam.clients import GAMClient

      # After
      from pygeai_gam.clients import GAMClient

2. Update test dependencies in ``pyproject.toml`` or ``requirements-dev.txt``
3. Ensure ``pygeai-gam`` is installed in your test environment

Why This Change?
=================

The migration to a separate package provides several benefits:

1. **Separation of Concerns**
   
   - The gam functionality is independent from the core pygeai SDK
   - Each package can evolve at its own pace

2. **Reduced Dependencies**
   
   - Users who don't need gam features don't install unnecessary dependencies
   - Smaller package size for the core pygeai SDK

3. **Better Maintainability**
   
   - GAM-specific updates don't require releasing a new pygeai version
   - Clearer issue tracking and feature development

4. **Independent Versioning**
   
   - ``pygeai`` and ``pygeai-gam`` can have independent version numbers
   - Breaking changes in gam don't affect core SDK users

Timeline
========

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - Version
     - pygeai.gam Status
     - Action Required
   * - pygeai ≤0.6.x
     - Available (bundled)
     - None
   * - pygeai 0.7.0
     - Deprecated (with warnings)
     - Migrate to pygeai-gam to maintain functionality
   * - pygeai 0.8.0
     - Removed
     - Must use pygeai-gam

Support
=======

If you encounter issues during migration:

1. Check the `Troubleshooting Guide <#common-issues-and-solutions>`_
2. Review the pygeai-gam documentation in the package's `docs/` directory
3. Contact support at geai-sdk@globant.com

Quick Reference
===============

Migration Checklist
-------------------

.. code-block:: text

   ☐ Install pygeai-gam: pip install pygeai-gam
   ☐ Run migration script: migrate-pygeai-gam /path/to/project --dry-run
   ☐ Review proposed changes (with --verbose)
   ☐ Apply migration: migrate-pygeai-gam /path/to/project --backup
   ☐ Update project dependencies (requirements.txt, pyproject.toml)
   ☐ Run tests to verify migration
   ☐ Remove backup files: find . -name "*.py.bak" -delete
   ☐ Update documentation/README if needed
   ☐ Commit changes to version control

Import Mapping
--------------

.. code-block:: python

   # Main client
   from pygeai.gam.clients import GAMClient
   from pygeai_gam import GAMClient  # ✓

   # Endpoints
   from pygeai.gam.endpoints import GAM_ENDPOINTS
   from pygeai_gam.endpoints import GAM_ENDPOINTS  # ✓

   # PKCE
   from pygeai.gam import PKCEHelper
   from pygeai_gam import PKCEHelper  # ✓

   # Exceptions
   from pygeai.gam.exceptions import GAMException
   from pygeai_gam.exceptions import GAMException  # ✓
