# 🏦 FinanceGY

**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.

---

## Installation

```bash
pip install financegy
```

---

## Quick Start

```python
import financegy

# --------------------------
# Core Data Retrieval
# --------------------------

# Get a list of all traded securities
securities = financegy.get_securities()

# Get active market securities (symbol + company name) from the most recent session page
active_securities = financegy.get_active_securities()

# Get the most recent trading session number
recent_session = financegy.get_recent_session()

# Get the full name of a security by its ticker symbol
security_name = financegy.get_security_by_symbol("DDL")

# Get the most recent trade data for a security
recent_trade = financegy.get_recent_trade("DDL")

# Get the most recent closing/last trade price (same most-recent session)
previous_close = financegy.get_previous_close("DDL")

# Get absolute price change vs previous session close
price_change = financegy.get_price_change("DDL")

# Get percent price change vs previous session close
price_change_percent = financegy.get_price_change_percent("DDL")

# Get all trade data for the most recent year (for the security)
recent_year_trades = financegy.get_security_recent_year("DDL")

# Get the earliest financial year available for the security
earliest_year = financegy.get_security_earliest_year("DDL")

# Get the latest financial year available for the security
latest_year = financegy.get_security_latest_year("DDL")

# Get the full trade history for a security (all years combined)
full_history = financegy.get_security_full_history("DDL")

# Get trade data for a specific trading session (all securities)
session_trades = financegy.get_session_trades("1136")

# Get trade data for a specific security in a session
security_session_trade = financegy.get_security_session_trade("DDL", "1136")

# Search for securities by name or symbol
search_results = financegy.search_securities("DDL")

# Get all trades for a specific year
year_trades = financegy.get_trades_for_year("DDL", "2019")

# Get historical trades within a date range - supports: yyyy / mm/yyyy / dd/mm/yyyy
historical_trades = financegy.get_historical_trades(
    symbol="DDL",
    start_date="01/06/2020",
    end_date="01/2022"
)

# --------------------------
# Analytics / Calculations
# --------------------------

# Get the latest session info (dict returned from most recent trade)
latest_session = financegy.get_latest_session_for_symbol("DDL")

# Average last traded price over a session range (inclusive)
avg_price_range = financegy.get_sessions_average_price("DDL", "1100", "1136")

# Average last traded price over the last N sessions or 1M, 3M, 6M 1Y (ending at latest session)
avg_price_latest = financegy.get_average_price("DDL", "1M")

# Volatility over the last N sessions (weekly log-return volatility + annualized)
volatility = financegy.get_sessions_volatility("DDL", 30)

# Year-to-date high and low traded prices
ytd_high_low = financegy.get_ytd_high_low("DDL")

# Get top market gainers and losers (based on % price change)
movers = financegy.get_movers()

# Get overall market snapshot (Symbol | Name | LTP | Prev Close | Price Change | PC% | YTD High | YTD Low)
market_snapshot = financegy.get_market_snapshot()

# --------------------------
# Portfolio / Position Calculations
# --------------------------

# Calculate the current market value of a position
position_value = financegy.calculate_position_value("DDL", shares=50)

# Calculate unrealized gain or loss for a position
position_return = financegy.calculate_position_return(
    symbol="DDL",
    shares=50,
    purchase_price=250
)

# Calculate percentage return for a position
position_return_percent = financegy.calculate_position_return_percent(
    symbol="DDL",
    shares=50,
    purchase_price=250
)

# Portfolio-level summary
portfolio = [
    {"symbol": "DTC", "shares": 100, "purchase_price": 300},
    {"symbol": "DDL", "shares": 50, "purchase_price": 250},
]

portfolio_summary = financegy.calculate_portfolio_summary(portfolio)

# --------------------------
# Utilities
# --------------------------

# Convert results to a DataFrame
df = financegy.to_dataframe(securities)

# Export to CSV / Excel
financegy.save_to_csv(securities, filename="securities.csv", silent=True)
financegy.save_to_excel(securities, filename="securities.xlsx", silent=True)

# Clear FinanceGY cache directory
financegy.clear_cache(silent=True)
```

---

## API Reference

### Core Data Retrieval

| Function                                              | Description                                                                          |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `get_securities()`                                    | Returns all currently traded securities on the GSE.                                  |
| `get_active_securities()`                             | Returns active securities (symbol and company name) from the most recent session.    |
| `get_recent_session()`                                | Returns the most recent trading session number.                                      |
| `get_session_date()`                                  | Returns the date for a specified trading session.                              |
| `get_security_by_symbol(symbol)`                      | Returns the full security name for a ticker symbol.                                  |
| `get_recent_trade(symbol)`                            | Returns the most recent trade information for the given security.                    |
| `get_security_recent_year(symbol)`                    | Returns all trade data for the most recent year available for the selected security. |
| `get_security_earliest_year(symbol)`                  | Returns the earliest financial year available for the selected security.             |
| `get_security_latest_year(symbol)`                    | Returns the latest financial year available for the selected security.               |
| `get_security_full_history(symbol)`                   | Returns the full trade history for the selected security across all available years. |
| `get_session_trades(session)`                         | Returns trade data for all securities during a specific trading session.             |
| `get_security_session_trade(symbol, session)`         | Returns trade data for a specific security during a specific session.                |
| `search_securities(query)`                            | Searches securities whose names or ticker symbols match the given query.             |
| `get_trades_for_year(symbol, year)`                   | Returns all trade records for a specific security during a given year.               |
| `get_historical_trades(symbol, start_date, end_date)` | Returns historical trades within the specified date range.                           |

### Analytics / Calculation Functions

| Function                                                         | Description                                                                 |
|------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `get_previous_close(symbol)`                                     | Returns the most recent closing/last trade price.                          |
| `get_price_change(symbol)`                                       | Returns absolute price difference vs previous session close.               |
| `get_price_change_percent(symbol)`                               | Returns percent price change vs previous session close.                    |
| `get_latest_session_for_symbol(symbol)`                          | Returns the latest trade dictionary for the symbol.                        |
| `get_sessions_average_price(symbol, session_start, session_end)` | Returns the average last traded price over a session range.                |
| `get_average_price(symbol, session_number)`                      | Returns the average last traded price over the last N sessions or 1M, 3M, 6M or 1Y.|
| `get_sessions_volatility(symbol, session_number)`                | Returns volatility (log-return + annualized) over the last N sessions.     |
| `get_ytd_high_low(symbol)`                                       | Returns year-to-date highest and lowest traded prices.                     |
| `get_movers()`                                                   | Returns top market gainers, losers, and unchanged securities (% change).   |
| `get_market_snapshot()`                                          | Returns overall market snapshot (Symbol, Company Name, LTP, Prev Close, Price Change, Price Change %, YTD High, YTD Low). |


### Portfolio / Position Functions

| Function                                                            | Description                                                                     |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `calculate_position_value(symbol, shares)`                          | Calculates the current market value of a position using the latest trade price. |
| `calculate_position_return(symbol, shares, purchase_price)`         | Calculates the unrealized gain or loss for a position.                          |
| `calculate_position_return_percent(symbol, shares, purchase_price)` | Calculates the percentage return for a position.                                |
| `calculate_portfolio_summary(positions)`                            | Computes a full portfolio summary including totals and per-position breakdown.  |

### Utilities

| Function                                                               | Description                                                   |
| ---------------------------------------------------------------------- | ------------------------------------------------------------- |
| `to_dataframe(data)`                                                   | Converts FinanceGY list/dict results into a pandas DataFrame. |
| `save_to_csv(data, filename="output.csv", path=None, silent=False)`    | Saves data to a CSV file.                                     |
| `save_to_excel(data, filename="output.xlsx", path=None, silent=False)` | Saves data to an Excel file.                                  |
| `clear_cache(silent=False)`                                            | Completely clears the FinanceGY cache directory.              |

---

## Caching System

FinanceGY includes a lightweight local caching system designed to speed up repeated requests and reduce unnecessary calls.

Whenever you call a data retrieval function (such as `get_securities()` or `get_recent_trade()`), FinanceGY automatically checks whether a cached response already exists for that specific query:

- If a valid cache file (less than 3 days old) is found, the result is returned instantly from the cache.
- If the cache is missing, disabled, or older than one week, FinanceGY fetches fresh data from the GSE and updates the cache automatically.

All cache files are stored in a local `cache/` directory as small JSON files containing the retrieved data and a timestamp.

You can manually clear all cached data at any time:

```python
import financegy

financegy.clear_cache()
```

This will delete all cached files and force the next data request to fetch fresh data directly from the source.

If you prefer to bypass the cache for a specific call, simply pass `use_cache=False` to any function. For example:

```python
# Force a fresh fetch from the GSE, ignoring cached data
recent_trade = financegy.get_recent_trade("DDL", use_cache=False)
```

By default, caching is enabled for all supported functions unless explicitly turned off.

---

## License

This project is licensed under the **MIT License**

---

## Example Use Case

```python
import financegy

ddl_recent = financegy.get_security_recent("DDL")
print(ddl_recent)
```
