from pathlib import Path
import gzip
import pickle


def store_pickle(obj, filepath):
    """
    Store a compressed "pickle" of the object in the "pickle_data" directory
    and return the full path to it.

    :param obj: Any Python object that can be pickled
    :param filepath: str or  Path object
    :return: Path object

    Example in lieu of Doctest to avoid writing out a file.

        my_object = {'a': 4, 'b': 5, 'c': [1, 2, 3]}
        gender_analysis.common.store_pickle(my_object, 'path_to_pickle/example_pickle.pgz')

    """
    if isinstance(filepath, str):
        filepath = Path(filepath)
    if not isinstance(filepath, Path):
        raise ValueError(f'filepath must be a str or path object, not type {type(filepath)}')

    if filepath.stem == '':
        filepath = Path(str(filepath) + '.pgz')

    with gzip.GzipFile(filepath, 'w') as fileout:
        pickle.dump(obj, fileout)
    return filepath