AcumaticaClient

# The v0.4.8 way - everything is dynamic!
from easy_acumatica import AcumaticaClient

# Initialize - this discovers your entire instance
client = AcumaticaClient(
    base_url="https://your-instance.acumatica.com",
    username="your_username",
    password="your_password",
    tenant="YourTenant",
    branch="YourBranch"
)

# Models are generated and ready to use
print(f"Available models: {dir(client.models)}")

# Services are attached dynamically
print(f"Available services: {[attr for attr in dir(client) if attr.endswith('s') and not attr.startswith('_')]}")

# Use them immediately with full type safety!
customer = client.customers.get_by_id("ABCCOMP")
print(f"Customer: {customer.CustomerName}")

from easy_acumatica import AcumaticaClient

# Method 1: Direct parameters
client = AcumaticaClient(
    base_url="https://your-instance.acumatica.com",
    username="api_user",
    password="secure_password",
    tenant="Company",
    branch="MAIN"
)

# Method 2: Environment variables
# Set: ACUMATICA_URL, ACUMATICA_USERNAME, etc.
client = AcumaticaClient()

# Method 3: Mix of both (env vars as defaults)
client = AcumaticaClient(
    tenant="Company",  # Override specific values
    branch="BRANCH01"
)

# Method 4: Using a config object
from easy_acumatica import AcumaticaConfig

config = AcumaticaConfig(
    base_url="https://your-instance.acumatica.com",
    username="api_user",
    password="secure_password",
    tenant="Company",
    endpoint_name="Default",
    endpoint_version="23.200.001"
)
client = AcumaticaClient(config=config)

# Configure advanced behaviors
client = AcumaticaClient(
    base_url="https://your-instance.acumatica.com",
    username="api_user",
    password="secure_password",
    tenant="Company",
    
    # Session behavior
    persistent_login=True,      # Keep session alive (default)
    retry_on_idle_logout=True,  # Auto-retry on 401 (default)
    
    # Performance tuning
    rate_limit_calls_per_second=10.0,  # API throttling
    timeout=60,                        # Request timeout in seconds
    
    # SSL and security
    verify_ssl=True,           # Verify SSL certificates
    
    # API targeting
    endpoint_name="Default",   # Which endpoint to use
    endpoint_version=None,     # Auto-detect latest version
    
    # Localization
    locale="en-US"            # API locale setting
)

# The client discovers everything on initialization
client = AcumaticaClient(...)

# See what was discovered
print("\nAvailable Services:")
for attr in dir(client):
    if attr.endswith('s') and not attr.startswith('_'):
        service = getattr(client, attr)
        print(f"  - client.{attr} -> {type(service).__name__}")

print("\nAvailable Models:")
for model_name in sorted(dir(client.models)):
    if not model_name.startswith('_'):
        model = getattr(client.models, model_name)
        print(f"  - {model_name}: {len(model.__dataclass_fields__)} fields")

# Check if custom entities exist
if hasattr(client, 'custom_entity'):
    print("\nCustom entity service available!")

# Check for custom fields
customer_fields = client.models.Customer.__dataclass_fields__
custom_fields = [f for f in customer_fields if f.startswith('Usr')]
print(f"\nCustom fields on Customer: {custom_fields}")

# All models follow Python dataclass patterns

# Create a new customer
customer = client.models.Customer(
    CustomerID="PYTHN001",
    CustomerName="Python Customer",
    CustomerClass="DEFAULT",
    # Your custom fields are here too!
    UsrCustomField="Custom Value" if hasattr(client.models.Customer, 'UsrCustomField') else None
)

# Models support all standard operations
print(customer.CustomerID)  # PYTHN001
print(customer.__dict__)    # See all fields

# Nested models work seamlessly
order = client.models.SalesOrder(
    OrderType="SO",
    CustomerID="PYTHN001",
    Details=[
        client.models.SalesOrderDetail(
            InventoryID="WIDGET",
            Quantity=5
        )
    ]
)

# Type hints work perfectly in your IDE
# Your editor knows all fields and their types!

# Services provide intuitive CRUD operations

# GET - Retrieve by keys
customer = client.customers.get_by_id("PYTHN001")

# GET - With field selection
opts = QueryOptions(filter=F.CustomerID == "PYTHN001", select=["CustomerID","CustomerName","Balance"])
customer = client.customers.get_list(options=opts)

# LIST - Get multiple records
all_customers = client.customers.get_list()

# LIST - With OData parameters
from easy_acumatica import F, QueryOptions

# CREATE - Add new record
new_customer = client.models.Customer(
    CustomerID="PYTHN002",
    CustomerName="Another Python Customer"
)
created = client.customers.put_entity(new_customer)

# UPDATE - Modify existing
customer.CustomerName = "Updated Name"
updated = client.customers.put_entity(customer)

# DELETE - Remove record
client.customers.delete_by_id("PYTHN002")

from easy_acumatica import (
    AcumaticaException,
    AcumaticaAuthError,
    AcumaticaAPIError,
    AcumaticaNetworkError,
    AcumaticaTimeoutError,
    AcumaticaNotFoundError
)

try:
    # This might fail in various ways
    customer = client.customers.get_by_id("UNKNOWN")
    
except AcumaticaNotFoundError as e:
    # Record doesn't exist
    print(f"Customer not found: {e}")
    
except AcumaticaAuthError as e:
    # Authentication failed
    print(f"Auth error: {e}")
    # Maybe refresh credentials
    
except AcumaticaTimeoutError as e:
    # Request timed out
    print(f"Timeout after {e.timeout}s")
    # Maybe retry with longer timeout
    
except AcumaticaAPIError as e:
    # API returned an error
    print(f"API error {e.status_code}: {e.message}")
    print(f"Details: {e.details}")
    
except AcumaticaNetworkError as e:
    # Network-level error
    print(f"Network error: {e}")
    
except AcumaticaException as e:
    # Catch-all for any Acumatica-related error
    print(f"Acumatica error: {e}")