mspu 0.0.1__tar.gz

mspu-0.0.1/.gitignore

@@ -0,0 +1,172 @@
+#https://github.com/github/gitignore/blob/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/user/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# build
+/_build
+
+# mkdocs documentation
+/site
+
+# sphinx documentation
+/docs/api/api
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+Footer
+
+# Visual Studio Code settings
+.vscode/

mspu-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sean Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mspu-0.0.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: mspu
+Version: 0.0.1
+Summary: Ma's python utils package.
+Author-email: Sean Ma <sean.sl.ma@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: polars
+Description-Content-Type: text/markdown
+
+# mspu
+
+My python utils package. It includes some commonly used functions, like `gen_rand_df` and `explode_date_range`.
+
+## How to install `mspu`
+
+Using `pip`:
+```sh
+pip install mspu
+```
+
+Using `uv`:
+```sh
+uv pip install mspu
+```
+
+## The document for `mspu`
+
+Visit the [document](https://seanslma.github.io/mspu) for more details.

mspu-0.0.1/README.md

@@ -0,0 +1,19 @@
+# mspu
+
+My python utils package. It includes some commonly used functions, like `gen_rand_df` and `explode_date_range`.
+
+## How to install `mspu`
+
+Using `pip`:
+```sh
+pip install mspu
+```
+
+Using `uv`:
+```sh
+uv pip install mspu
+```
+
+## The document for `mspu`
+
+Visit the [document](https://seanslma.github.io/mspu) for more details.

mspu-0.0.1/docs/api/_static/custom.css

@@ -0,0 +1,22 @@
+/* Force line break before ALL parameters including the first */
+dt.sig.sig-object em.sig-param::before {
+    content: "\A    ";
+    white-space: pre;
+}
+
+/* Ensure commas stay inline */
+dt.sig.sig-object .w {
+    display: inline;
+}
+
+/* Add comma after last parameter and force line break after it */
+dt.sig.sig-object em.sig-param:last-of-type::after {
+    content: ",\A";
+    white-space: pre;
+}
+
+/* Alternative: target the closing parenthesis directly */
+dt.sig.sig-object span.sig-paren:last-of-type::before {
+    content: "\A";
+    white-space: pre;
+}

mspu-0.0.1/docs/api/_templates/copyright.html

@@ -0,0 +1 @@
+{{ copyright_html }}

mspu-0.0.1/docs/api/conf.py

@@ -0,0 +1,111 @@
+# -- Path setup --------------------------------------------------------------
+import os
+import sys
+from datetime import datetime
+
+# Add the project root to the path so Sphinx can find the 'mspu' package
+sys.path.insert(0, os.path.abspath('../../'))
+
+# -- Project information -----------------------------------------------------
+project = 'mspu'
+copyright = '2026, Sean Ma'
+author = 'Sean Ma'
+release = '0.0.1'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    # Core Sphinx extensions
+    'sphinx.ext.autodoc',  # To include documentation from docstrings
+    'sphinx.ext.viewcode',  # To link to the source code
+    'sphinx.ext.autosummary',  # To automatically generate summary tables
+    # Additional utility extensions
+    # 'sphinx_autodoc_typehints',  # To display type hints nicely
+    'numpydoc',  # To support NumPy style docstrings
+    'sphinx_design',  # For badges, cards, etc.
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_copybutton',  # To add copy buttons to code blocks
+]
+
+# Strip the >>> and ... prompts so copied code is clean
+copybutton_prompt_text = '>>> |\\.\\.\\. '
+copybutton_prompt_is_regexp = True
+
+# The suffix(es) of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# The theme to use. This enables the PyData Sphinx Theme.
+html_theme = 'pydata_sphinx_theme'
+
+# The theme options
+html_theme_options = {
+    'github_url': 'https://github.com/seanslma/mspu',
+    'secondary_sidebar_items': [],  # Disable the secondary sidebar items (page toc)
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom CSS files
+html_css_files = [
+    'custom.css',
+]
+
+# If true, the rest sources are included in the HTML build as _sources/foo.txt.
+html_copy_source = False
+
+# disable default copyright
+html_show_copyright = False
+
+# Add back to home link and copyright in the footer
+html_context = {
+    'copyright_html': f'<a href="/" title="Go to Main Home Page">🏠 Back to Home</a><br>Copyright &copy; {datetime.now().year} Sean Ma'
+}
+
+# If true, "Created using Sphinx" is shown in the HTML footer.
+html_show_sphinx = True
+
+# -- Autodoc configuration ---------------------------------------------------
+# Type hints: show in signature only (not in description)
+# autodoc_typehints = "signature"
+
+# Use short format for type hints
+# autodoc_typehints_format = "short"
+
+# Preserve the defaults in signatures
+autodoc_preserve_defaults = True
+
+# -- Sphinx autodoc typehints configuration ----------------------------------
+# This prevents duplicate parameter documentation in the body
+# typehints_defaults = "comma"
+
+# -- Numpydoc configuration ---------------------------------------------------
+# Don't show class members automatically
+numpydoc_show_class_members = False
+
+# Don't show type hints in the parameter descriptions since they're in signature
+numpydoc_show_type_hint = False
+
+# Mock imports for modules that are not available in the documentation environment
+autodoc_mock_imports = []
+
+# Global setup for doctests
+doctest_global_setup = """
+import numpy as np
+import polars as pl
+# anything else needed globally
+"""

mspu-0.0.1/docs/api/data.rst

@@ -0,0 +1,15 @@
+.. _api.data:
+
+data
+======
+
+.. currentmodule:: mspu.data
+
+Functions
+~~~~~~~~~
+
+.. autosummary::
+   :toctree: api/
+   :nosignatures:
+
+   gen_rand_df

mspu-0.0.1/docs/api/index.rst

@@ -0,0 +1,20 @@
+.. mspu documentation master file
+
+mspu API Reference
+==================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   mspu
+   data
+   pandas
+   polars
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

mspu-0.0.1/docs/api/mspu.rst

@@ -0,0 +1,14 @@
+mspu
+====
+
+My python utils package.
+
+Submodules
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    data
+    pandas
+    polars

mspu-0.0.1/docs/api/pandas.rst

@@ -0,0 +1,18 @@
+.. _api.pandas:
+
+pandas
+======
+
+.. currentmodule:: mspu.pandas
+
+Functions
+~~~~~~~~~
+
+.. autosummary::
+   :toctree: api/
+   :nosignatures:
+
+   pd_ht
+   df_diffs
+   explode_date_range
+   pa_mod

mspu-0.0.1/docs/api/polars.rst

@@ -0,0 +1,20 @@
+.. _api.polars:
+
+polars
+======
+
+.. currentmodule:: mspu.polars
+
+Functions
+~~~~~~~~~
+
+.. autosummary::
+   :toctree: api/
+   :nosignatures:
+
+   pl_ht
+   inf_count
+   nan_count
+   nul_count
+   lowercase_polars_df
+   to_float32_polars_df

mspu-0.0.1/docs/build.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# Step 1: Clean any old builds
+rm -rf _build/html/
+
+# Step 2: Change to the docs directory
+cd docs
+
+# Step 3: Build the MkDocs guide first (creates the '_build/html' folder)
+mkdocs build --site-dir ../_build/html
+
+# Step 4: Build Sphinx directly into the compiled MkDocs '_build/api' folder
+sphinx-build -b html api ../_build/html/api
+
+# Step 5: Return to the root directory
+cd ..
+
+# Copy to the final build directory
+cp -a ./_build/html/. ../seanslma.github.io/mspu/

mspu-0.0.1/docs/guide/index.md

@@ -0,0 +1,13 @@
+# Welcome to mspu
+
+mspu is a Python package designed for providing some commonly used functions.
+
+This user guide is intended to walk you through getting started, providing examples, and explaining core concepts.
+
+## Structure
+
+User Guide (You Are Here): Conceptual overviews, installation steps, and tutorials.
+
+API Reference (External Link): Detailed, auto-generated documentation for every function and class (powered by Sphinx).
+
+Check out the Tutorial to see how mspu works!

mspu-0.0.1/docs/guide/tutorial.md

@@ -0,0 +1,117 @@
+# Quick Tutorial: Using explode_date_range
+
+This tutorial shows you how to use the `mspu.pandas.explode_date_range` function.
+
+## 1. Install the package
+
+First, ensure you have the `mspu` package installed:
+```sh
+pip install mspu
+```
+
+## 2. Displaying dataframe
+
+When you print a pandas DataFrame, sometimes the default settings are not good enough so you need to adjust the display width, number of rows and columns. Here we provide a simple function for your convinence.
+
+```py
+import pandas as pd
+from mspu.pandas import pd_ht
+pd.DataFrame.ht = pd_ht
+df = pd.DataFrame({
+  'foo': [1.12345, 2.98765, 3.14159],
+  'bar': [7, 8, 9],
+  'ham': ['x', 'y', 'z'],
+})
+df.ht(n=1, c=2, r=3)
+```
+
+The output:
+```
+shape: (3, 3)
+     foo  ...  ham
+0  1.123  ...    x
+2  3.142  ...    z
+```
+
+## 3. Creating random data
+
+The `gen_rand_df` can be used to create random data in a pandas DataFrame for testing.
+
+In this example, we'll create a dataframe with one string column, two timestamp columns, one integer column, and two float columns, for one year with a resolution of one minute.
+
+```py
+from mspu.data import gen_rand_df
+
+df = gen_rand_df(
+    nrow=100,
+    str_cols=1,
+    ts_cols={
+        'count': 2,
+        'name': ['start_date', 'end_date'],
+        'start_date': ['2020-01-01', '2023-01-01'],
+        'end_date': ['2023-01-01', '2025-01-01'],
+        'freq': 'MS',
+        'random': True,
+    },
+    int_cols=1,
+    float_cols=2,
+)
+df.ht(1, c=-1, r=2)
+```
+Outputs:
+```
+shape: (100, 6)
+       s1 start_date   end_date  i1    f1    f2
+0   IZD8v 2022-10-01 2023-12-01   0  1.43  1.78
+99  y5HeH 2020-12-01 2024-07-01   0  1.13  1.11
+
+```
+
+## 4. Using the `explode_date_range` function
+
+This function can be used to explode two datetime columns in a pandas DataFrame to a list of datetime values as a new column. It's about `30x` faster than using the pandas `df.explode` function.
+```py
+import time
+from mspu.pandas import explode_date_range
+
+# assume we already created the df in the previous section
+t0 = time.time()
+df_exploded = explode_date_range(
+    df=df,
+    start_date_col='start_date',
+    end_date_col='end_date',
+    date_col='ts',
+    freq='30min',
+    inclusive='left',
+    drop_date_cols=True,
+)
+print(f'mspu explode time: {time.time() - t0:.3f} seconds')
+df_exploded.ht(2,r=2)
+```
+Outputs:
+```
+mspu explode time: 0.235 seconds
+shape: (4415424, 5)
+            s1  i1    f1    f2                  ts
+0        IZD8v   0  1.43  1.78 2022-10-01 00:00:00
+1        IZD8v   0  1.43  1.78 2022-10-01 00:30:00
+4415422  y5HeH   0  1.13  1.11 2024-06-30 23:00:00
+4415423  y5HeH   0  1.13  1.11 2024-06-30 23:30:00
+```
+
+Now let's use `explode` from pandas:
+```py
+t1 = time.time()
+df['ts'] = [
+    pd.date_range(start, end, freq='30min', inclusive='left')
+    for start, end in zip(df['start_date'].values, df['end_date'].values)
+]
+df_exploded_pandas = df.drop(columns=['start_date', 'end_date']).explode('ts')
+print(f'pandas explode time: {time.time() - t1:.3f} seconds')
+print(df_exploded.equals(df_exploded_pandas.reset_index(drop=True)))
+```
+Outputs:
+```
+pandas explode time: 4.117 seconds
+True
+```

mspu-0.0.1/docs/hooks.py

@@ -0,0 +1,50 @@
+import re
+import datetime
+
+
+def on_page_markdown(markdown, **kwargs):
+    """
+    Add blank line before lists that don't have one.
+    Matches: text\n- item (no blank line)
+    Replaces with: text\n\n- item (adds blank line)
+    """
+    # Pattern: non-empty line followed by newline and list item
+    # Negative lookbehind ensures previous line isn't already blank
+    pattern = r'(?<!\n)\n([-*+]\s)'
+    replacement = r'\n\n\1'
+
+    return re.sub(pattern, replacement, markdown)
+
+
+def on_config(config):
+    # Replace {year} once globally
+    now = datetime.datetime.now()
+    # date = now.strftime('%-d %b %Y')
+    copyright = config.get('copyright', '')
+    config['raw_copyright'] = copyright.replace('{year}', str(now.year))
+
+    return config
+
+
+def on_page_context(context, page, config, nav):
+    # Determine which date to use
+    if page.is_homepage:
+        display_date = datetime.datetime.now().strftime('%-d %b %Y')
+    else:
+        # Try to get the Git date from plugin metadata
+        display_date = (
+            page.meta.get('git_revision_date_localized')
+            or page.meta.get('revision_date')
+            or datetime.datetime.now().strftime('%-d %b %Y')
+        )
+    updated_at = f'Last updated on {display_date}'
+
+    # Remove it from metadata to avoid auto creating `last updated` field
+    page.meta.pop('git_revision_date_localized', None)
+
+    # Build a per-page footer WITHOUT mutating the global config
+    # Use context['copyright'] instead of config['copyright']
+    copyright = config['raw_copyright']
+    context['config']['copyright'] = f'{copyright}<br>{updated_at}'
+
+    return context