Delivery#

morningstar_data.utils.delivery.deliver( config: DeliveryConfig | List[DeliveryConfig], wait_for_delivery: bool = False, ) → dict#

Upcoming Feature

Delivers a file from a notebook to an email or FTP.

Parameters:

config (md.utils.DeliveryConfig) –
An object that holds the delivery configuration information.
All delivery methods (email, FTP, Delivery Profile) contains
- file_path (:obj: str, required): the path to the file that will be delivered, including file name and extension.
- delivered_file_name (:obj: str, optional): parameter for the user to specify the file name to be used when
  delivered. No file extension should be provided. If it’s omitted, the file_path value will use as default filename.
- include_timestamp (:obj: bool, optional): optional parameter for the user append a timestamp to the file name. Default value will be False. The format will be YYYYMMDDHHMMSS.
For an email, it contains
- method (DeliveryType): DeliveryType.EMAIL in this case.
- email_address (str): email_address to send the file to.
For FTP, it contains
- method (DeliveryType): DeliveryType.FTP in this case.
- user_name (str): the user_name to login to the ftp server.
- password (str): the password to login to the ftp server.
- server (str): the ftp server to use.
- folder (str): the folder on the ftp server to upload the file to.
For a Delivery Profile, it contains
- method (DeliveryType): DeliveryType.DELIVERY_PROFILE in this case.
- delivery_profile_id (str): delivery_profile_id that was setup by MDS. Can be retrieved with get_delivery_profile()
wait_for_delivery (bool) – Flag to poll the api to check the delivery status or not. (True=show status)

Returns:

dict: A dictionary with the ‘job_id’, ‘message’, ‘delivery_status’ keys containing information about the delivery status

Examples:

Deliver to an email address.

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

# Email example
    * For single file
        delivery_config = md.utils.DeliveryConfig(method=md.utils.DeliveryType.EMAIL, email_address="test@email.com", file_path="test_export.csv", delivered_file_name="Delivered_File_123", include_timestamp=True)
        md.utils.deliver(config=delivery_config)

    * For multiple files
        df = pd.DataFrame({'a':[1], 'b':[2]})
        df.to_csv("test_export2.csv")

        delivery_config1 = md.utils.DeliveryConfig(file_path="test_export.csv", method=md.utils.DeliveryType.EMAIL, email_address="test1@email.com", delivered_file_name="Delivered_File_123", include_timestamp=True)
        delivery_config2 = md.utils.DeliveryConfig(file_path="test_export2.csv", method=md.utils.DeliveryType.EMAIL, email_address="test2@email.com", delivered_file_name="Delivered_File_123", include_timestamp=True)
        md.utils.deliver([delivery_config1, delivery_config2])

Deliver to a ftp server.

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

# FTP example
delivery_config = md.utils.DeliveryConfig(method=md.utils.DeliveryType.FTP, user_name="test", password="test", server="ts.ftp.com", folder="data/", file_path="test_export.csv", delivered_file_name="Delivered_File_123")
md.utils.deliver(config=delivery_config)

Deliver to a Delivery Profile

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

# Delivery Profile example
delivery_config = md.utils.DeliveryConfig(method=md.utils.DeliveryType.DELIVERY_PROFILE, delivery_profile_id="1234", file_path="test_export.csv", delivered_file_name="Delivered_File_123")
md.utils.deliver(config=delivery_config)

Multiple delivery within a single notebook.

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

ftp_delivery_config = md.utils.DeliveryConfig(file_path="test_export.csv", method=md.utils.DeliveryType.FTP, user_name="test", password="test", server="ts.ftp.com", folder="data/", delivered_file_name="Delivered_File_123")
email_delivery_config = md.utils.DeliveryConfig(file_path="test_export.csv", method=md.utils.DeliveryType.EMAIL, email_address="test@email.com", delivered_file_name="Delivered_File_123", include_timestamp=False)
md.utils.deliver([ftp_delivery_config, email_delivery_config])

Multiple delivery for multiple files.

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export2.csv")

ftp_delivery_config = md.utils.DeliveryConfig(file_path="test_export.csv", method=md.utils.DeliveryType.FTP, user_name="test", password="test", server="ts.ftp.com", folder="data/", delivered_file_name="Delivered_File_123", include_timestamp=False)
email_delivery_config = md.utils.DeliveryConfig(file_path="test_export2.csv", method=md.utils.DeliveryType.EMAIL, email_address="test@email.com", delivered_file_name="Delivered_File_123", include_timestamp=True)
md.utils.deliver([ftp_delivery_config, email_delivery_config])

Deliver with a specific filename.

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

# Email example
delivery_config = md.utils.DeliveryConfig(method=md.utils.DeliveryType.EMAIL, email_address="test@email.com", file_path="test_export.csv", delivered_file_name="Delivered_Dataframe_123", include_timestamp=True)
md.utils.deliver(config=delivery_config)
# As we set include_timestamp to True, the file delivered will be named "Delivered_Dataframe_123_2024022819184484.csv"

delivery_config = md.utils.DeliveryConfig(method=md.utils.DeliveryType.EMAIL, email_address="test@email.com", file_path="test_export.csv", delivered_file_name="Delivered_Dataframe_123")
md.utils.deliver(config=delivery_config)
# If include_timestamp set to False or if omitted, the file delivered will be named "Delivered_Dataframe_123.csv"

Deliver without the delivered_file_name property

import morningstar_data as md
import pandas as pd

df = pd.DataFrame({'a':[1], 'b':[2]})
df.to_csv("test_export.csv")

delivery_config = md.utils.DeliveryConfig(method=md.utils.DeliveryType.EMAIL, email_address="test@email.com", file_path="test_export.csv", include_timestamp=True)
md.utils.deliver(config=delivery_config)
# In this example we omitted the delivered_file_name property, so the file delivered will use the file_path and be named "test_export_2024022819184484.csv"

Errors:

AccessDeniedError: Raised when the user is not authenticated.

UnauthorizedDeliveryException: Raised when the user does not have permissions to deliver artifacts.

BadRequestError: Raised when the user does not provide a properly formatted request.

InternalServerError: Raised when the server encounters an unhandled error.

NetworkExceptionError: Raised when the request fails to reach the server due to a network error.

FileNotFoundError: Raised when the file path specified to be delivered does not exist