Ejemplos de Uso Básico

Esta sección proporciona ejemplos básicos de cómo usar Portfolio Toolkit como biblioteca de Python. Estos ejemplos están basados en el código de trabajo real de los comandos CLI.

Cargar una Cartera

La forma más común de trabajar con carteras es cargarlas desde archivos JSON usando el cargador integrado:

from portfolio_toolkit.data_provider.yf_data_provider import YFDataProvider
from portfolio_toolkit.portfolio.load_portfolio_json import load_portfolio_json
from portfolio_toolkit.cli.commands.utils import load_json_file

# Cargar datos de cartera desde archivo JSON
data = load_json_file('portfolio.json')

# Crear un proveedor de datos de Yahoo Finance
data_provider = YFDataProvider()

# Cargar la cartera con datos de mercado
portfolio = load_portfolio_json(data, data_provider=data_provider)

# Imprimir información básica de la cartera
print(f"Nombre de Cartera: {portfolio.name}")
print(f"Moneda Base: {portfolio.currency}")
print(f"Número de Activos: {len(portfolio.assets)}")

Para el formato JSON de cartera, ve Formato JSON de Cartera.

Ver Transacciones de Cartera

Puedes ver y exportar transacciones de cartera de diferentes maneras:

Transacciones de Activos

from portfolio_toolkit.asset.portfolio_asset import PortfolioAsset

# Obtener todas las transacciones de activos como DataFrame
transactions_df = PortfolioAsset.to_dataframe(portfolio.assets)
print(transactions_df)

# Exportar a CSV
transactions_df.to_csv('asset_transactions.csv', index=False)
print("Transacciones de activos exportadas a CSV")

Transacciones de Efectivo

from portfolio_toolkit.account.account import Account

# Obtener transacciones de cuenta de efectivo como DataFrame
cash_df = Account.to_dataframe(portfolio.account)
print(cash_df)

# Exportar a CSV
cash_df.to_csv('cash_transactions.csv', index=False)
print("Transacciones de efectivo exportadas a CSV")

Salida de ejemplo:

📊 Transacciones de activos de cartera
============================================================
ticker    date        type  quantity     price currency
AAPL   2023-01-20     buy      50.0    150.25      USD
MSFT   2023-02-10     buy      30.0    280.50      USD

Ver Posiciones Actuales

Obtener posiciones abiertas para una fecha específica:

from portfolio_toolkit.position.get_open_positions import get_open_positions
from portfolio_toolkit.position.print_open_positions import print_open_positions
from portfolio_toolkit.position.valued_position import ValuedPosition

# Obtener posiciones abiertas para una fecha específica
date_str = "2025-07-30"
open_positions = get_open_positions(portfolio.assets, date_str)

# Imprimir posiciones en consola
print_open_positions(open_positions)

# Convertir a DataFrame para análisis
positions_df = ValuedPosition.to_dataframe(open_positions)
print(positions_df)

# Exportar posiciones a CSV
positions_df.to_csv('current_positions.csv')

Salida de ejemplo:

📊 Posiciones Abiertas al 2025-07-30
============================================================
Ticker  Cantidad  Precio Actual  Valor Mercado  Ganancia/Pérdida (%)
AAPL         50         208.62      10,431.00         +38.5%
MSFT         30         445.91      13,377.30         +59.2%

Análisis de Rendimiento

Analizar el rendimiento de la cartera a través de múltiples períodos de tiempo:

from portfolio_toolkit.position.compare_open_positions import compare_open_positions
from portfolio_toolkit.utils import get_last_periods

# Obtener las últimas 4 semanas para comparación
periods = get_last_periods(n=4, period_type='weeks', include_current=True)

# Comparar posiciones a través de estos períodos
comparison_df = compare_open_positions(portfolio, periods, display='return')
print("Comparación de rendimiento (retornos):")
print(comparison_df)

# Comparar valores de posición en lugar de retornos
values_df = compare_open_positions(portfolio, periods, display='value')
print("Comparación de valores de posición:")
print(values_df)

# Exportar datos de rendimiento
comparison_df.to_csv('performance_analysis.csv')

Salida de ejemplo:

📊 Resumen de Rendimiento - Últimas 4 Semanas
============================================================
        S27 2025    S28 2025    S29 2025    S30 2025
AAPL    -           3.33%       2.86%       1.92%
MSFT    -           -1.25%      4.17%       2.10%
============================================================

Visualizar Datos de Cartera

Create visualizations of your portfolio:

Position Charts

from portfolio_toolkit.position.plot_open_positions import plot_open_positions
from portfolio_toolkit.plot.engine import PlotEngine

# Get open positions
date_str = "2025-07-30"
open_positions = get_open_positions(portfolio.assets, date_str)

# Create pie chart of positions
chart_data = plot_open_positions(open_positions, group_by="Ticker")
PlotEngine.plot(chart_data)

# Group by country
country_chart = plot_open_positions(open_positions, group_by="Country")
PlotEngine.plot(country_chart)

# Group by sector
sector_chart = plot_open_positions(open_positions, group_by="Sector")
PlotEngine.plot(sector_chart)

Portfolio Evolution

from portfolio_toolkit.portfolio.plot_evolution import plot_portfolio_evolution
from portfolio_toolkit.portfolio.time_series_portfolio import create_time_series_portfolio_from_portfolio

# Create time series portfolio for plotting
ts_portfolio = create_time_series_portfolio_from_portfolio(portfolio)

# Plot portfolio evolution over time
line_data = plot_portfolio_evolution(ts_portfolio)
PlotEngine.plot(line_data)

Working with Period Utilities

Use the period utilities for time-based analysis:

from portfolio_toolkit.utils.period import get_current_period, get_last_periods, Period

# Get current period
current_week = get_current_period('week')
current_month = get_current_period('month')
current_quarter = get_current_period('quarter')
current_year = get_current_period('year')

print(f"Current week: {current_week.label}")
print(f"Period: {current_week.start_date} to {current_week.end_date}")

# Get last periods
last_quarters = get_last_periods(n=4, period_type='quarters', include_current=False)

for period in last_quarters:
    print(f"{period.label}: {period.start_date} to {period.end_date}")

# Create custom period
custom_period = Period(
    label="Q1 2025",
    start_date=date(2025, 1, 1),
    end_date=date(2025, 3, 31)
)

Error Handling

Handle common errors when working with portfolio data:

try:
    # Load portfolio
    data = load_json_file('portfolio.json')
    portfolio = load_portfolio_json(data, data_provider)

except FileNotFoundError:
    print("Portfolio file not found")

except ValueError as e:
    print(f"Invalid portfolio format: {e}")

except Exception as e:
    print(f"Error loading portfolio: {e}")

try:
    # Get positions for invalid date
    positions = get_open_positions(portfolio.assets, "invalid-date")

except ValueError as e:
    print(f"Invalid date format: {e}")

Data Export Patterns

Common patterns for exporting data:

# Export with conditional logic
def export_data(data_df, output_file=None):
    if output_file:
        data_df.to_csv(output_file, index=False)
        print(f"✅ Results saved to: {output_file}")
    else:
        print(data_df.to_string())

# Usage examples
positions_df = ValuedPosition.to_dataframe(open_positions)
export_data(positions_df, 'positions.csv')  # Save to file
export_data(positions_df)                   # Print to console

Complete Analysis Example

Here’s a complete example that performs comprehensive portfolio analysis:

from portfolio_toolkit.data_provider.yf_data_provider import YFDataProvider
from portfolio_toolkit.portfolio.load_portfolio_json import load_portfolio_json
from portfolio_toolkit.position.get_open_positions import get_open_positions
from portfolio_toolkit.position.compare_open_positions import compare_open_positions
from portfolio_toolkit.utils import get_last_periods
from portfolio_toolkit.cli.commands.utils import load_json_file
from datetime import date

def comprehensive_analysis(portfolio_path, analysis_date="2025-07-30"):
    """
    Perform comprehensive portfolio analysis
    """
    # Load portfolio
    data = load_json_file(portfolio_path)
    data_provider = YFDataProvider()
    portfolio = load_portfolio_json(data, data_provider=data_provider)

    print(f"=== Portfolio Analysis: {portfolio.name} ===")
    print(f"Base Currency: {portfolio.currency}")
    print(f"Analysis Date: {analysis_date}")
    print("=" * 50)

    # 1. Current positions
    print("\\n📊 Current Positions:")
    open_positions = get_open_positions(portfolio.assets, analysis_date)
    positions_df = ValuedPosition.to_dataframe(open_positions)
    print(positions_df.to_string())

    # 2. Performance analysis
    print("\\n📈 Performance Analysis (Last 4 Weeks):")
    periods = get_last_periods(n=4, period_type='weeks', include_current=True)
    performance_df = compare_open_positions(portfolio, periods, display='return')
    print(performance_df.to_string())

    # 3. Asset transactions summary
    print("\\n💰 Asset Transactions:")
    from portfolio_toolkit.asset.portfolio_asset import PortfolioAsset
    transactions_df = PortfolioAsset.to_dataframe(portfolio.assets)
    print(f"Total transactions: {len(transactions_df)}")
    print(transactions_df.head().to_string())

    # 4. Cash transactions summary
    print("\\n🏦 Cash Account:")
    from portfolio_toolkit.account.account import Account
    cash_df = Account.to_dataframe(portfolio.account)
    print(f"Total cash transactions: {len(cash_df)}")

    # 5. Export all data
    positions_df.to_csv('analysis_positions.csv', index=False)
    performance_df.to_csv('analysis_performance.csv')
    transactions_df.to_csv('analysis_transactions.csv', index=False)
    cash_df.to_csv('analysis_cash.csv', index=False)

    print("\\n✅ Analysis complete. Data exported to CSV files.")
    return portfolio

# Run the analysis
if __name__ == "__main__":
    portfolio = comprehensive_analysis('portfolio.json')

Best Practices

Always use data providers: Don’t load portfolios without a data provider:

# Good
data_provider = YFDataProvider()
portfolio = load_portfolio_json(data, data_provider=data_provider)

Handle date formats consistently: Use YYYY-MM-DD format for dates:

# Good
positions = get_open_positions(portfolio.assets, "2025-07-30")

Export data conditionally: Allow both console output and file export:

def display_or_export(df, output_file=None):
    if output_file:
        df.to_csv(output_file, index=False)
        print(f"✅ Saved to {output_file}")
    else:
        print(df.to_string())

Use DataFrame conversions: Most portfolio objects have to_dataframe() methods:

# Convert to DataFrame for analysis
df = ValuedPosition.to_dataframe(positions)
summary_stats = df.describe()

Period utilities for time analysis: Use the period utilities for consistent time handling:

# Get periods consistently
periods = get_last_periods(n=6, period_type='months', include_current=True)

This documentation shows you how to use the Portfolio Toolkit library based on the actual working code from the CLI commands, ensuring that all examples will work correctly.