Price Providers

A price provider is used to provide historical or current prices for securities.

Bundled Providers

NiveshPy comes bundled with a few useful providers.

Provider Name	Description	Command
AMFI	Provide mutual fund prices from AMFI.	niveshpy prices sync --provider amfi

Custom Providers

You can create your own custom price provider for NiveshPy with Python.

In your pyproject.toml file, include an entry point with the group niveshpy.providers.price.

[project.entry-points."niveshpy.providers.price"] # (1)
my_provider = "my_plugin:MyPluginFactory" # (2)

1. This needs to be added as-is to ensure NiveshPy can find your provider.
2. Replace my_provider with a unique key, and replace the string with a reference to your PluginFactory class.

Create a class my_plugin.MyPluginFactory that follows the protocol ProviderFactory. This factory will be responsible for actually creating the provider object with the input file and password.

The create_provider method must return an instance of a class that follows the protocol Provider.

The get_provider_info method must return an object of type ProviderInfo

Usage

To use a custom price provider, install it in the same virtual environment as NiveshPy and run the command:

niveshpy prices sync --provider my_provider

NiveshPy will use the name defined in your pyproject.toml as a unique key (in this example, my_provider).

Warning

If another installed price provider has the same key, your provider may be overwritten. If this happens, a warning will be logged. If you find yourself in this situation, you can change your provider key or advise the user to uninstall the other provider.

Shell Completion

NiveshPy CLI supports shell completion. If the user types the partial command niveshpy prices sync --provider ... and presses Tab, the CLI will look for providers with keys starting with the partial key entered by the user (or all providers if no key is provided). Depending on the terminal, the CLI will show a list of all such keys along with the name defined in your ProviderInfo.name

Tip

For this reason, it is recommended that your provider factory return a ProviderInfo object quickly. Do not write any initialization code in your provider factory. Any initialization code can be placed in the create_provider method as that will only be called after the user has run the relevant command.

API Reference

ProviderInfo dataclass

ProviderInfo(name: str, description: str, supports_historical: bool = True, supports_latest: bool = True, max_concurrent_requests: int = 0)

Model for provider metadata.

description instance-attribute

description: str

Brief description of what the provider does.

max_concurrent_requests class-attribute instance-attribute

max_concurrent_requests: int = field(default=0)

Maximum number of concurrent requests allowed (0 = no limit).

Currently not enforced by the application. It may be used in the future to limit concurrency when fetching data from providers that have rate limits.

name instance-attribute

name: str

Human-readable name of the provider.

supports_historical class-attribute instance-attribute

supports_historical: bool = field(default=True)

Indicates if the provider can fetch historical price data.

supports_latest class-attribute instance-attribute

supports_latest: bool = field(default=True)

Indicates if the provider can fetch the latest/current price.

Provider

Bases: Protocol

Protocol for price provider classes.

fetch_historical_prices

fetch_historical_prices(security: Security, start_date: date, end_date: date) -> Iterable[PriceCreate]

Fetch historical prices for a security.

Parameters:

Name	Type	Description	Default
security	Security	The security to fetch prices for	required
start_date	date	Start date (inclusive)	required
end_date	date	End date (inclusive)	required

Returns:

Type	Description
Iterable[PriceCreate]	An iterable of PriceCreate objects.

Source code in niveshpy/models/provider.py

def fetch_historical_prices(
    self,
    security: Security,
    start_date: datetime.date,
    end_date: datetime.date,
) -> Iterable[PriceCreate]:
    """Fetch historical prices for a security.

    Args:
        security: The security to fetch prices for
        start_date: Start date (inclusive)
        end_date: End date (inclusive)

    Returns:
        An iterable of PriceCreate objects.
    """
    ...

fetch_latest_price

fetch_latest_price(security: Security) -> PriceCreate

Fetch the latest price for a security.

Parameters:

Name	Type	Description	Default
security	Security	The security to fetch price for	required

Returns:

Type	Description
PriceCreate	A PriceCreate object.

Source code in niveshpy/models/provider.py

def fetch_latest_price(self, security: Security) -> PriceCreate:
    """Fetch the latest price for a security.

    Args:
        security: The security to fetch price for

    Returns:
        A PriceCreate object.
    """
    ...

get_priority

get_priority(security: Security) -> int | None

Get the priority of this provider for the given security.

Lower numbers = higher priority. Providers are tried in priority order when multiple providers can handle the same security.

Returns:

Type	Description
int | None	An integer representing the priority (e.g., 10, 20, 30).
int | None	Return None if the provider cannot handle the given security.

Source code in niveshpy/models/provider.py

def get_priority(self, security: Security) -> int | None:
    """Get the priority of this provider for the given security.

    Lower numbers = higher priority. Providers are tried in priority order
    when multiple providers can handle the same security.

    Returns:
        An integer representing the priority (e.g., 10, 20, 30).
        Return None if the provider cannot handle the given security.
    """
    ...

ProviderFactory

Bases: Protocol

Protocol for provider factory classes.

create_provider classmethod

create_provider() -> Provider

Create a provider instance.

Returns:

Type	Description
Provider	An instance of a Provider.

Source code in niveshpy/models/provider.py

@classmethod
def create_provider(cls) -> Provider:
    """Create a provider instance.

    Returns:
        An instance of a Provider.
    """
    ...

get_provider_info classmethod

get_provider_info() -> ProviderInfo

Get metadata about the provider.

Returns:

Type	Description
ProviderInfo	A ProviderInfo object containing metadata about the provider.

Source code in niveshpy/models/provider.py

@classmethod
def get_provider_info(cls) -> ProviderInfo:
    """Get metadata about the provider.

    Returns:
        A ProviderInfo object containing metadata about the provider.
    """
    ...