Codalpy

https://github.com/yghaderi/codalpy
Admin
Codalpy is a Python library designed for retrieving and refining financial data from the Iranian...
Tokens:4,578
Snippets:21
Trust Score:6.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install codalpy

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Use pip to install the library.

```bash
python -m pip install codalpy
```

--------------------------------

### Codal Class Initialization

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/autoapi/codalpy/index.html

Initializes the Codal client to interact with financial data.

```APIDOC
## Codal(issuer, from_jdate, to_jdate)

### Description
Initializes the Codal client with the target issuer and the date range in Jalali format.

### Parameters
- **issuer** (str) - The name or symbol of the issuer.
- **from_jdate** (str) - Start date in Jalali format (YYYY-MM-DD).
- **to_jdate** (str) - End date in Jalali format (YYYY-MM-DD).
```

--------------------------------

### Codal Class Initialization

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

The Codal class is the main entry point for interacting with the library. It requires the issuer name and a date range in Jalali format.

```APIDOC
## Codal(issuer, from_jdate, to_jdate)

### Description
Initializes the Codal client to fetch financial reports for a specific issuer within a given date range.

### Parameters
- **issuer** (str) - Required - The name of the company or issuer.
- **from_jdate** (str) - Required - Start date in Jalali format (e.g., "1401/01/01").
- **to_jdate** (str) - Required - End date in Jalali format (e.g., "1404/12/29").
```

--------------------------------

### Retrieve Fund Monthly Portfolio Data

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/_sources/autoapi/codalpy/index.rst.txt

Initializes the Codal client with an issuer and date range, then fetches the monthly portfolio report.

```python
>>> from codalpy import Codal
>>> codal = Codal(issuer = "اهرم", from_jdate= "1404-04-04", to_jdate="1404-06-06")
>>> codal.fund_monthly_portfolio()
```

--------------------------------

### Codal(issuer, from_jdate, to_jdate)

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/_sources/autoapi/codalpy/index.rst.txt

Initializes the Codal client with the specified issuer and date range in Jalali format.

```APIDOC
### Constructor
`Codal(issuer: str, from_jdate: str, to_jdate: str)`

### Parameters
- **issuer** (str) - The name of the issuer (e.g., "اهرم").
- **from_jdate** (str) - The start date in Jalali format (e.g., "1404-04-04").
- **to_jdate** (str) - The end date in Jalali format (e.g., "1404-06-06").
```

--------------------------------

### Fetch Fund Monthly Portfolio

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieve the monthly portfolio status for an investment fund.

```python
from codalpy import Codal
codal = Codal(issuer = "اهرم", from_jdate= "1404-04-04", to_jdate="1404-06-06")
codal.fund_monthly_portfolio()
"""
shape: (603, 18)
┌──────────────────────────────┬────────────┬────────────────┬──────────────────┬───┬────────┬─────────────────────────────────┬─────────────────────────────────┬─────────────────────────────────┐
│ name                         ┆ volume_beg ┆ total_cost_beg ┆ net_proceeds_beg ┆ … ┆ symbol ┆ title                           ┆ url                             ┆ attachment_url                  │
│ ---                          ┆ ---        ┆ ---            ┆ ---              ┆   ┆ ---    ┆ ---                             ┆ ---                             ┆ ---                             │
│ str                          ┆ i64        ┆ i64            ┆ i64              ┆   ┆ str    ┆ str                             ┆ str                             ┆ str                             │
╞══════════════════════════════╪════════════╪════════════════╪══════════════════╪═══╪════════╪═════════════════════════════════╪═════════════════════════════════╪═════════════════════════════════╡
│ آهن و فولاد غدیر ایرانیان     ┆ 24500000   ┆ 140495106806   ┆ 123719463000     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ اقتصادی و خودکفایی آزادگان   ┆ 58949663   ┆ 428681824109   ┆ 363313257531     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ البرزدارو                    ┆ 266248175  ┆ 853755414625   ┆ 982697425906     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ الحاوی                       ┆ 79400000   ┆ 175805992152   ┆ 102290130720     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ الکتریک‌ خودرو شرق‌            ┆ 117032944  ┆ 427355209792   ┆ 310735053213     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ …                            ┆ …          ┆ …              ┆ …                ┆ … ┆ …      ┆ …                               ┆ …                               ┆ …                               │
│ کشت و دامداری فکا            ┆ 38000000   ┆ 42921313500    ┆ 137950282800     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ کویر تایر                    ┆ 84043466   ┆ 168768973101   ┆ 619056648665     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ ح . سرمایه گذاری‌البرز(هلدینگ‌ ┆ 0          ┆ 0              ┆ 0                ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ سنگ آهن گهرزمین              ┆ 0          ┆ 0              ┆ 0                ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ ح . سنگ آهن گهرزمین          ┆ 0          ┆ 0              ┆ 0                ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
└──────────────────────────────┴────────────┴────────────────┴──────────────────┴───┴────────┴─────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┘
"""
```

--------------------------------

### monthly_activity()

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieves the monthly activity report for the initialized issuer.

```APIDOC
## monthly_activity()

### Description
Fetches the monthly activity report for the configured issuer and date range.
```

--------------------------------

### balance_sheet()

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieves the balance sheet for the initialized issuer.

```APIDOC
## balance_sheet()

### Description
Fetches the balance sheet report for the configured issuer and date range.
```

--------------------------------

### Codal.fund_monthly_portfolio()

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/autoapi/codalpy/codal/index.html

Retrieves the monthly stock portfolio for ETF funds as a polars.DataFrame.

```APIDOC
## Method: Codal.fund_monthly_portfolio()

### Description
Retrieves the monthly stock portfolio data for ETF funds based on the issuer and date range specified during the initialization of the Codal client.

### Returns
- **polars.DataFrame** - A DataFrame containing the monthly portfolio details including name, volume, costs, and associated metadata.

### Usage Example
```python
from codalpy import Codal
codal = Codal(issuer = "اهرم", from_jdate= "1404-04-04", to_jdate="1404-06-06")
df = codal.fund_monthly_portfolio()
```
```

--------------------------------

### Fetch Monthly Activity

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieve monthly activity reports for a specific issuer within a date range.

```python
from codalpy import Codal
codal = Codal(
    issuer = "شپدیس",
    from_jdate = "1404/01/01",
    to_jdate = "1404/12/29"
)
data = codal.monthly_activity()
```

--------------------------------

### fund_monthly_portfolio()

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/_sources/autoapi/codalpy/codal/index.rst.txt

Retrieves the monthly portfolio status report for the initialized issuer.

```APIDOC
## Method: fund_monthly_portfolio()

### Description
Fetches the monthly portfolio status report for the issuer defined in the Codal client instance.

### Returns
- **DataFrame** - A Polars DataFrame containing portfolio details such as name, volume, costs, proceeds, symbol, title, and report URLs.
```

--------------------------------

### income_statement()

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieves the income statement for the initialized issuer.

```APIDOC
## income_statement()

### Description
Fetches the income statement report for the configured issuer and date range.
```

--------------------------------

### fund_monthly_portfolio()

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieves the monthly portfolio status for investment funds.

```APIDOC
## fund_monthly_portfolio()

### Description
Fetches the portfolio status report for investment funds for the configured issuer and date range.
```

--------------------------------

### Retrieve ETF Monthly Portfolio

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/autoapi/codalpy/codal/index.html

Fetches the monthly stock portfolio for an ETF issuer as a polars DataFrame.

```python
>>> from codalpy import Codal
>>> codal = Codal(issuer = "اهرم", from_jdate= "1404-04-04", to_jdate="1404-06-06")
>>> codal.fund_monthly_portfolio()
shape: (603, 18)
┌──────────────────────────────┬────────────┬────────────────┬──────────────────┬───┬────────┬─────────────────────────────────┬─────────────────────────────────┬─────────────────────────────────┐
│ name                         ┆ volume_beg ┆ total_cost_beg ┆ net_proceeds_beg ┆ … ┆ symbol ┆ title                           ┆ url                             ┆ attachment_url                  │
│ ---                          ┆ ---        ┆ ---            ┆ ---              ┆   ┆ ---    ┆ ---                             ┆ ---                             ┆ ---                             │
│ str                          ┆ i64        ┆ i64            ┆ i64              ┆   ┆ str    ┆ str                             ┆ str                             ┆ str                             │
╞══════════════════════════════╪════════════╪════════════════╪══════════════════╪═══╪════════╪═════════════════════════════════╪═════════════════════════════════╪═════════════════════════════════╡
│ آهن و فولاد غدیر ایرانیان     ┆ 24500000   ┆ 140495106806   ┆ 123719463000     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ اقتصادی و خودکفایی آزادگان   ┆ 58949663   ┆ 428681824109   ┆ 363313257531     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ البرزدارو                    ┆ 266248175  ┆ 853755414625   ┆ 982697425906     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ الحاوی                       ┆ 79400000   ┆ 175805992152   ┆ 102290130720     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ الکتریک‌ خودرو شرق‌            ┆ 117032944  ┆ 427355209792   ┆ 310735053213     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ …                            ┆ …          ┆ …              ┆ …                ┆ … ┆ …      ┆ …                               ┆ …                               ┆ …                               │
│ کشت و دامداری فکا            ┆ 38000000   ┆ 42921313500    ┆ 137950282800     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ کویر تایر                    ┆ 84043466   ┆ 168768973101   ┆ 619056648665     ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ ح . سرمایه گذاری‌البرز(هلدینگ‌ ┆ 0          ┆ 0              ┆ 0                ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ سنگ آهن گهرزمین              ┆ 0          ┆ 0              ┆ 0                ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
│ ح . سنگ آهن گهرزمین          ┆ 0          ┆ 0              ┆ 0                ┆ … ┆ اهرم   ┆ صورت وضعیت پورتفوی صندوق سرمای… ┆ https://www.codal.ir/Reports/A… ┆ https://www.codal.ir/Reports/A… │
└──────────────────────────────┴────────────┴────────────────┴──────────────────┴───┴────────┴─────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┘
```

--------------------------------

### Fetch Balance Sheet

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieve the balance sheet for a specific issuer within a date range.

```python
from codalpy import Codal
codal = Codal(
    issuer = "شپدیس",
    from_jdate = "1401/01/01",
    to_jdate = "1404/12/29"
)
data = codal.balance_sheet()
```

--------------------------------

### Process Portfolio Attachment Downloads

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/_modules/codalpy/codal.html

Internal logic for iterating through letters, identifying attachments, and locating the correct Excel download endpoint for a specific issuer.

```python
self._query.category = QueryCategory.MONTHLY_ACTIVITY
self._query.letter_type = QueryLetterType.PORTFOLIO_POSITION
letters = self.letter()
df = pl.DataFrame()
for letter in letters:
    if letter.has_attachment:
        attachment = requests.get(letter.attachment_url, headers=HEADERS)
        xlsx_endpoint = find_download_endpoint(attachment.text)
        endpoint = ""
        if len(xlsx_endpoint) > 1:
            for i in xlsx_endpoint:
                if normalize_fs_item(self._issuer.symbol) in normalize_fs_item(
                    i["description"]
                ):
                    endpoint = i["link"]
                    break
        elif len(xlsx_endpoint) == 1:
            endpoint = xlsx_endpoint[0]["link"]
        if endpoint:
            xlsx = requests.get(
                f"{self._consts.base_url}/Reports/{endpoint}",
                stream=True,
                headers=HEADERS,
            )
```

--------------------------------

### Codal.fund_monthly_portfolio()

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/autoapi/codalpy/index.html

Retrieves the monthly portfolio status for a specific fund issuer within a defined date range.

```APIDOC
## Codal.fund_monthly_portfolio()

### Description
Fetches the monthly portfolio report for a fund. The instance must be initialized with an issuer, from_jdate, and to_jdate.

### Parameters
- None (uses instance attributes: issuer, from_jdate, to_jdate)

### Response
- Returns a Polars DataFrame containing portfolio details such as name, volume_beg, total_cost_beg, net_proceeds_beg, symbol, title, url, and attachment_url.
```

--------------------------------

### fund_monthly_portfolio()

Source: https://github.com/yghaderi/codalpy/blob/master/docs/_build/_sources/autoapi/codalpy/index.rst.txt

Retrieves the monthly portfolio status for the initialized issuer within the specified date range.

```APIDOC
### Method
`fund_monthly_portfolio()`

### Description
Fetches the monthly portfolio status report for the issuer defined during initialization. Returns a data structure containing columns such as name, volume_beg, total_cost_beg, net_proceeds_beg, symbol, title, url, and attachment_url.
```

--------------------------------

### Fetch Income Statement

Source: https://github.com/yghaderi/codalpy/blob/master/README.md

Retrieve the income statement for a specific issuer within a date range.

```python
from codalpy import Codal
codal = Codal(
    issuer = "شپدیس",
    from_jdate = "1401/01/01",
    to_jdate = "1404/12/29"
)
data = codal.income_statement()
```
Tokens:
Raw