mergeron 2024.738963.0__py3-none-any.whl → 2025.739265.0__py3-none-any.whl

mergeron-2025.739265.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.3
+Name: mergeron
+Version: 2025.739265.0
+Summary: Analyze merger enforcement policy using Python
+License: MIT
+Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI
+Author: Murthy Kambhampaty
+Author-email: smk@capeconomics.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: aenum (>=3.1.15,<4.0.0)
+Requires-Dist: attrs (>=23.2)
+Requires-Dist: bs4 (>=0.0.1)
+Requires-Dist: certifi (>=2023.11.17)
+Requires-Dist: google-re2 (>=1.1)
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: joblib (>=1.3)
+Requires-Dist: matplotlib (>=3.8)
+Requires-Dist: mpmath (>=1.3)
+Requires-Dist: msgpack (>=1.0)
+Requires-Dist: msgpack-numpy (>=0.4)
+Requires-Dist: scipy (>=1.12)
+Requires-Dist: sympy (>=1.12)
+Requires-Dist: tables (>=3.10.1)
+Requires-Dist: types-beautifulsoup4 (>=4.11.2)
+Requires-Dist: urllib3 (>=2.2.2,<3.0.0)
+Requires-Dist: xlrd (>=2.0.1,<3.0.0)
+Requires-Dist: xlsxwriter (>=3.1)
+Description-Content-Type: text/x-rst
+
+mergeron: Merger Policy Analysis using Python
+=============================================
+
+Visualize the sets of mergers conforming to concentration and diversion-ratio standards. Estimate intrinsic enforcement rates, and intrinsic clearance rates, under concentration, diversion ratio, GUPPI, CMCR, and IPR bounds using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions implied by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand. Download and analyze merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations (Second Requests) during 1996 to 2011.
+
+Here, enforcement rates derived with merger enforcement as being exogenous to firm conduct are defined as intrinsic enforcement rates, and similarly intrinsic clearance rates. Depending on the merger enforcement regime, or merger control regime, intrinsic enforcement rates may also not be the complement of intrinsic clearance rates, i.e, it is not necessarily true that the intrinsic clearance rate estimate for a given enforcement regime is 1 minus the intrinsic enforcement rate. In contrast, observed enforcement rates reflect the deterrent effects of merger enforcement on firm conduct as well as the effects of merger screening on the level of enforcement; and, by definition, the observed clearance rate is 1 minus the observed enforcement rate.
+
+Introduction
+------------
+
+Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`.core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary, as an array of share-pairs, and area. This module also includes a function for generating plots of concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+
+Module :code:`.gen.data_generation` includes the :code:`.gen.data_generation.MarketSample` which provides for a rich specification of shares and diversion ratios (:code:`.gen.data_generation.MarketSample.share_spec`), margins (:code:`.gen.data_generation.MarketSample.pcm_spec`, prices (:code:`.gen.data_generation.MarketSample.price_spec`), and HSR filing requirements (:code:`.gen.data_generation.MarketSample.hsr_filing_test_type`), and with methods for, (i) generating sample data (:code:`.gen.data_generation.MarketSample.generate_sample`), and (ii) computing the intrinsic enforcement rate and intrinsic clearance rate for the generated sample, given a method (:code:`.UPPAggrSelector`) of aggregating diversion ratio or GUPPI estimates for the firms in a merger (:code:`.gen.data_generation.MarketSample.estimate_enf_counts`). While the latter populate the properties, :code:`.gen.data_generation.MarketSample.data`
+and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.share_spec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
+
+By default, merging-firm shares are drawn with uniform distribution over the space :math:`s_1 + s_2 \leqslant 1` for an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution (see property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec`, of type, :code:`.gen.SHRDistribution`), with specified shape parameters (property `dist_parms` of :code:`.gen.data_generation.MarketSample.share_spec`. When drawing shares from the Dirichlet distribution, the user specifies the `firm_count_weights` property of :code:`.gen.data_generation.MarketSample.share_spec`, as a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). If the property `firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.share_spec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
+
+Recapture ratios can be specified as, "proportional", "inside-out", or "outside-in" (see :code:`.RECForm`). The "inside-out" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) results in recapture ratios consistent with MNL demand, given merging-firms' in-market shares and a default recapture ratio. The "outside-in" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) yields diversion ratios from purchase probabilities drawn at random for :math:`N+1` goods, with market shares and recapture ratios for the :math:`N` goods in the putative market (see, :code:`.gen.ShareSpec`) computed from the simulated choice probabilities. The "outside-in" specification requires specification of the distribution of markets over firm counts (the default being uniform distirbution over markets with 2 to 7 firms pre-merger), and Dirichlet-distributed shares, with optional parameters (the default being a "flat" Dirichlet distribution, i.e., one with all parameters being 1). The parameters of the Dirichlet distribution can, for example, be specified to increase (decrease) the probability of drawing mergers to monopoly relative to that probability associated with the Flat Dirichlet specification, by setting the first 2 specified parameters at higher (lower) values relative to the others. Lastly, the "proportional" form of recapture ratio (`recapture_form` = :code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" calibration. See, for example, Coate (2011).
+
+Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or a built-in empirical distribution (see, :code:`.gen.PCMSpec`). The in-built empirical margin distribution is based on resampling margin data published by Prof. Damodaran of NYU Stern School of Business (see Notes), using an estimated Gaussian KDE. The second merging firm's margin (per the property `firm2_pcm_constraint` of :code:`.gen.data_generation.MarketSample.pcm_spec`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
+
+Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified (see, :code:`.gen.PriceSpec`). Prices may also be defined by imposing cost symmetry on firms in the sample, with fixed unit marginal costs normalized to 1 unit, such that prices equal :math:`1 / (1 - \pmb{m})`, where :math:`\pmb{m}` represents the array of margins for firms in the sample.
+
+The market sample may be restricted to mergers meeting the HSR filing requirement under two alternative approaches: in the one, the smaller of the two merging firms meets the lower HSR size threshold ($10 million, as adjusted) and the larger of the two merging firms meets the size test if it's share is no less than 10 times the share of the smaller firm. In the other, the :math:`n`-th firm's size is maintained as $10 million, as adjusted (see, :code:`.gen.SSZConstant`), and a merger meets the HSR filing test if either, (a.) the smaller merging firm is no smaller than the n-th firm and the larger merging firm is at 10-times as large as the n-th firm, or (b.) the smaller merging firm's market share is in excess of 10%; in effect this version of the test maintains that if the smaller merging firm's market share exceeds 10%, the value of the transaction exceeds $200 million, as adjusted, and the size-of-person test is eliminated (see, FTC (2008, p. 12); the above are simplifications of the statutory HSR filing requirements). The second assumption avoids the unfortunate assumption in the first that, within the resulting sample, the larger merging firm be at least 10 times as large as the smaller merging firm, as a consequence of the full definition of the HSR filing requirement.
+
+The full specification of a market sample is given in a :code:`.gen.data_generation.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`.gen.data_generation.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`.gen.data_generation.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`.gen.data_generation.MarketSample.estimate_enf_counts` on a :code:`.gen.data_generation.MarketSample` object without first invoking :code:`.gen.data_generation.MarketSample.generate_sample`. Note, however, that this strategy does not retain the market sample in memory in the interests of conserving memory and maintaining high performance (the user can specify that the market sample and enforcement statistics be stored to permanent storage; when saving to current PCIe NVMe storage, the performance penalty is slight, but can be considerable if saving to SATA storage).
+
+Enforcement statistics based on FTC investigations data and test data are tabulated using methods provided in :code:`.gen.enforcement_stats`.
+
+Programs demonstrating the use of this package are included in the sub-package, :code:`.demo`.
+
+This package includes  a class, :code:`.core.pseudorandom_numbers.MultithreadedRNG` for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple CPU cores, be they virtual, logical, or physical cores. This class is an adaptation from the documentation for the external :code:`numpy.random` subpackage, from the discussion on, "`Multithreaded generation <https://numpy.org/doc/stable/reference/random/multithreading.html>`_"; the version included here permits selection of the distribution with pre-tests to catch and inform on common errors. To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.pseudorandom_numbers as prng
+
+Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
+
+.. code-block:: python
+
+    import mergeron.core.data_generation as dgl
+
+    help(dgl.MarketSample)
+
+.. rubric:: References
+
+.. _coate2011:
+
+Coate, M. B. (2011). Benchmarking the upward pricing pressure model with Federal Trade
+Commission evidence. Journal of Competition Law & Economics, 7(4), 825--846. URL: https://doi.org/10.1093/joclec/nhr014.
+
+.. _ftc_premerger_guide2:
+
+FTC Premerger Notification Office. “To File or Not to File: When You Must File a Premerger Notification Report Form”. 2008 (September, revised). URL: https://www.ftc.gov/sites/default/files/attachments/premerger-introductory-guides/guide2.pdf
+
+
+.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+   :alt: Poetry
+   :target: https://python-poetry.org/
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :alt: Ruff
+   :target: https://github.com/astral-sh/ruff/
+
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :alt: Checked with mypy
+   :target: https://mypy-lang.org/
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT/
+
+

mergeron-2025.739265.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+mergeron/__init__.py,sha256=TA29lm9xq1AOShjbOs4dXujCClb_MMCLlKN6ej8VC08,1581
+mergeron/core/__init__.py,sha256=jPGd0okmvNOdWnTu4biR4hqnL29IERaY4Olv8mS02ko,188
+mergeron/core/empirical_margin_distribution.py,sha256=uDgXXNNL4ln_f1rnvfOxrpokeuha6qQXpi0c7ZGE58U,8726
+mergeron/core/ftc_merger_investigations_data.py,sha256=_Qno1_oWcHmDd60j8YX6BLUSLeAn-DU6KpvMOcbCIaE,28728
+mergeron/core/guidelines_boundaries.py,sha256=ci6bNVNKGynCnXFoQXit0jyhpQW8hw-Y37DpozuQETg,15245
+mergeron/core/guidelines_boundary_functions.py,sha256=SoTamDsKrThqDfoNTHeGp2ntiwhzscWmkAbIWrBtUq4,34885
+mergeron/core/guidelines_boundary_functions_extra.py,sha256=ytTWxYk7FkGLQubkQXrniwP_2ZlYssp4rmOxy4_7480,11292
+mergeron/core/pseudorandom_numbers.py,sha256=VepI_YU5oMkTExjyN9OyfiB3UmTDR2cq4N1DAmYZbm4,9233
+mergeron/data/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
+mergeron/data/damodaran_margin_data.xls,sha256=Qggl1p5nkOMJI8YUXhkwXQRz-OhRSqBTzz57N0JQyYA,79360
+mergeron/data/damodaran_margin_data_dict.msgpack,sha256=sr6s4L69kposEpzGI7jpPb4ULz0UpY-bEYfeNi6UlRA,57621
+mergeron/data/ftc_invdata.msgpack,sha256=WBFHgi7Ld4R-h2zL2Zc3TOIlKqVrbVFMH1LoI4-T-M0,264664
+mergeron/demo/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
+mergeron/demo/visualize_empirical_margin_distribution.py,sha256=_1SWKqFJNqKV_yA3v2tmzl8Th3CC3SXpb6VGiwGGuN0,2373
+mergeron/gen/__init__.py,sha256=6A1HVewEEwLo4JtZZ61ShzhU2phEeNfTxmTPlpi5LXY,17215
+mergeron/gen/data_generation.py,sha256=nzCWVJBXYxloR6J6MamFM0MUbDzguhARCAEksYkX1Dw,16872
+mergeron/gen/data_generation_functions.py,sha256=cIYkE4DcBXdEbEIeCk2lG9rLKblhdYZPDMJdGMS2dKE,29022
+mergeron/gen/enforcement_stats.py,sha256=ZjrV_VkFMF0D1myc-fj-W99M1EhJMA9-nCfyE5g9e54,10890
+mergeron/gen/upp_tests.py,sha256=bQfxigqHc8bdsd5SjMyKKa07weTEcAdJvLCiTrhgzAE,12547
+mergeron/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+mergeron-2025.739265.0.dist-info/METADATA,sha256=nkTdrTqjVT4tc6ljYRuCFykz0X-TsABN3zxyEe9ALnE,14494
+mergeron-2025.739265.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+mergeron-2025.739265.0.dist-info/RECORD,,

{mergeron-2024.738963.0.dist-info → mergeron-2025.739265.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.9.0
+Generator: poetry-core 2.0.1
 Root-Is-Purelib: true
 Tag: py3-none-any

mergeron/License.txt

@@ -1,16 +0,0 @@
-mergeron
-========
-
-Copyright 2017-2024 S. Murthy Kambhampaty
-
-MIT License
------------
-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.
-
-Exceptions
-----------
-Modules provided in the mergeron.ext subpackage are redistributed under the license published within each module.

mergeron/core/InCommon RSA Server CA cert chain.pem

@@ -1,68 +0,0 @@
------BEGIN CERTIFICATE-----
-MIIF+TCCA+GgAwIBAgIQRyDQ+oVGGn4XoWQCkYRjdDANBgkqhkiG9w0BAQwFADCB
-iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
-cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV
-BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTQx
-MDA2MDAwMDAwWhcNMjQxMDA1MjM1OTU5WjB2MQswCQYDVQQGEwJVUzELMAkGA1UE
-CBMCTUkxEjAQBgNVBAcTCUFubiBBcmJvcjESMBAGA1UEChMJSW50ZXJuZXQyMREw
-DwYDVQQLEwhJbkNvbW1vbjEfMB0GA1UEAxMWSW5Db21tb24gUlNBIFNlcnZlciBD
-QTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJwb8bsvf2MYFVFRVA+e
-xU5NEFj6MJsXKZDmMwysE1N8VJG06thum4ltuzM+j9INpun5uukNDBqeso7JcC7v
-HgV9lestjaKpTbOc5/MZNrun8XzmCB5hJ0R6lvSoNNviQsil2zfVtefkQnI/tBPP
-iwckRR6MkYNGuQmm/BijBgLsNI0yZpUn6uGX6Ns1oytW61fo8BBZ321wDGZq0GTl
-qKOYMa0dYtX6kuOaQ80tNfvZnjNbRX3EhigsZhLI2w8ZMA0/6fDqSl5AB8f2IHpT
-eIFken5FahZv9JNYyWL7KSd9oX8hzudPR9aKVuDjZvjs3YncJowZaDuNi+L7RyML
-fzcCAwEAAaOCAW4wggFqMB8GA1UdIwQYMBaAFFN5v1qqK0rPVIDh2JvAnfKyA2bL
-MB0GA1UdDgQWBBQeBaN3j2yW4luHS6a0hqxxAAznODAOBgNVHQ8BAf8EBAMCAYYw
-EgYDVR0TAQH/BAgwBgEB/wIBADAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
-AwIwGwYDVR0gBBQwEjAGBgRVHSAAMAgGBmeBDAECAjBQBgNVHR8ESTBHMEWgQ6BB
-hj9odHRwOi8vY3JsLnVzZXJ0cnVzdC5jb20vVVNFUlRydXN0UlNBQ2VydGlmaWNh
-dGlvbkF1dGhvcml0eS5jcmwwdgYIKwYBBQUHAQEEajBoMD8GCCsGAQUFBzAChjNo
-dHRwOi8vY3J0LnVzZXJ0cnVzdC5jb20vVVNFUlRydXN0UlNBQWRkVHJ1c3RDQS5j
-cnQwJQYIKwYBBQUHMAGGGWh0dHA6Ly9vY3NwLnVzZXJ0cnVzdC5jb20wDQYJKoZI
-hvcNAQEMBQADggIBAC0RBjjW29dYaK+qOGcXjeIT16MUJNkGE+vrkS/fT2ctyNMU
-11ZlUp5uH5gIjppIG8GLWZqjV5vbhvhZQPwZsHURKsISNrqOcooGTie3jVgU0W+0
-+Wj8mN2knCVANt69F2YrA394gbGAdJ5fOrQmL2pIhDY0jqco74fzYefbZ/VS29fR
-5jBxu4uj1P+5ZImem4Gbj1e4ZEzVBhmO55GFfBjRidj26h1oFBHZ7heDH1Bjzw72
-hipu47Gkyfr2NEx3KoCGMLCj3Btx7ASn5Ji8FoU+hCazwOU1VX55mKPU1I2250Lo
-RCASN18JyfsD5PVldJbtyrmz9gn/TKbRXTr80U2q5JhyvjhLf4lOJo/UzL5WCXED
-Smyj4jWG3R7Z8TED9xNNCxGBMXnMete+3PvzdhssvbORDwBZByogQ9xL2LUZFI/i
-eoQp0UM/L8zfP527vWjEzuDN5xwxMnhi+vCToh7J159o5ah29mP+aJnvujbXEnGa
-nrNxHzu+AGOePV8hwrGGG7hOIcPDQwkuYwzN/xT29iLp/cqf9ZhEtkGcQcIImH3b
-oJ8ifsCnSbu0GB9L06Yqh7lcyvKDTEADslIaeSEINxhO2Y1fmcYFX/Fqrrp1WnhH
-OjplXuXE0OPa0utaKC25Aplgom88L2Z8mEWcyfoB7zKOfD759AN7JKZWCYwk
------END CERTIFICATE-----
------BEGIN CERTIFICATE-----
-MIIF3jCCA8agAwIBAgIQAf1tMPyjylGoG7xkDjUDLTANBgkqhkiG9w0BAQwFADCB
-iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
-cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV
-BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTAw
-MjAxMDAwMDAwWhcNMzgwMTE4MjM1OTU5WjCBiDELMAkGA1UEBhMCVVMxEzARBgNV
-BAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0plcnNleSBDaXR5MR4wHAYDVQQKExVU
-aGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNVBAMTJVVTRVJUcnVzdCBSU0EgQ2Vy
-dGlmaWNhdGlvbiBBdXRob3JpdHkwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIK
-AoICAQCAEmUXNg7D2wiz0KxXDXbtzSfTTK1Qg2HiqiBNCS1kCdzOiZ/MPans9s/B
-3PHTsdZ7NygRK0faOca8Ohm0X6a9fZ2jY0K2dvKpOyuR+OJv0OwWIJAJPuLodMkY
-tJHUYmTbf6MG8YgYapAiPLz+E/CHFHv25B+O1ORRxhFnRghRy4YUVD+8M/5+bJz/
-Fp0YvVGONaanZshyZ9shZrHUm3gDwFA66Mzw3LyeTP6vBZY1H1dat//O+T23LLb2
-VN3I5xI6Ta5MirdcmrS3ID3KfyI0rn47aGYBROcBTkZTmzNg95S+UzeQc0PzMsNT
-79uq/nROacdrjGCT3sTHDN/hMq7MkztReJVni+49Vv4M0GkPGw/zJSZrM233bkf6
-c0Plfg6lZrEpfDKEY1WJxA3Bk1QwGROs0303p+tdOmw1XNtB1xLaqUkL39iAigmT
-Yo61Zs8liM2EuLE/pDkP2QKe6xJMlXzzawWpXhaDzLhn4ugTncxbgtNMs+1b/97l
-c6wjOy0AvzVVdAlJ2ElYGn+SNuZRkg7zJn0cTRe8yexDJtC/QV9AqURE9JnnV4ee
-UB9XVKg+/XRjL7FQZQnmWEIuQxpMtPAlR1n6BB6T1CZGSlCBst6+eLf8ZxXhyVeE
-Hg9j1uliutZfVS7qXMYoCAQlObgOK6nyTJccBz8NUvXt7y+CDwIDAQABo0IwQDAd
-BgNVHQ4EFgQUU3m/WqorSs9UgOHYm8Cd8rIDZsswDgYDVR0PAQH/BAQDAgEGMA8G
-A1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEMBQADggIBAFzUfA3P9wF9QZllDHPF
-Up/L+M+ZBn8b2kMVn54CVVeWFPFSPCeHlCjtHzoBN6J2/FNQwISbxmtOuowhT6KO
-VWKR82kV2LyI48SqC/3vqOlLVSoGIG1VeCkZ7l8wXEskEVX/JJpuXior7gtNn3/3
-ATiUFJVDBwn7YKnuHKsSjKCaXqeYalltiz8I+8jRRa8YFWSQEg9zKC7F4iRO/Fjs
-8PRF/iKz6y+O0tlFYQXBl2+odnKPi4w2r78NBc5xjeambx9spnFixdjQg3IM8WcR
-iQycE0xyNN+81XHfqnHd4blsjDwSXWXavVcStkNr/+XeTWYRUc+ZruwXtuhxkYze
-Sf7dNXGiFSeUHM9h4ya7b6NnJSFd5t0dCy5oGzuCr+yDZ4XUmFF0sbmZgIn/f3gZ
-XHlKYC6SQK5MNyosycdiyA5d9zZbyuAlJQG03RoHnHcAP9Dc1ew91Pq7P8yF1m9/
-qS3fuQL39ZeatTXaw2ewh0qpKJ4jjv9cJ2vhsE/zB+4ALtRZh8tSQZXq9EfX7mRB
-VXyNWQKV3WKdwrnuWih0hKWbt5DHDAff9Yk2dDLWKMGwsAvgnEzDHNb842m1R0aB
-L6KCq9NjRHDEjf8tM7qtj3u1cIiuPhnPQCjY/MiQu12ZIvVS5ljFH4gxQ+6IHdfG
-jjxDah2nGN59PRbxYvnKkKj9
------END CERTIFICATE-----

mergeron/core/excel_helper.py

@@ -1,259 +0,0 @@
-"""
-Methods for writing data from Python to fresh Excel workbooks using
-the third-party package, `xlsxwriter`.
-
-Includes a flexible system of defining cell formats.
-
-"""
-
-from __future__ import annotations
-
-import enum
-from collections.abc import Mapping, Sequence
-from importlib.metadata import version
-from types import MappingProxyType
-from typing import Any
-
-import numpy as np
-import numpy.typing as npt
-import xlsxwriter  # type: ignore
-
-from .. import _PKG_NAME  # noqa: TID252
-
-__version__ = version(_PKG_NAME)
-
-
-@enum.unique
-class CFmtParent(dict[str, Any], enum.ReprEnum):  # type: ignore
-    """Unique mappings defining xlsxwirter Workbook formats"""
-
-    ...
-
-
-class CFmt(CFmtParent):
-    """
-    Initialize cell formats for xlsxwriter.
-
-    The mappings included here, and unions, etc. of them
-    and any others added at runtime, will be rendered
-    as xlsxWriter.Workbook.Format objects for writing
-    cell values to formatted cells in a spreadsheet.
-
-    See, https://xlsxwriter.readthedocs.io/format.html
-    """
-
-    XL_DEFAULT = MappingProxyType({"font_name": "Calibri", "font_size": 11})
-    XL_DEFAULT_2003 = MappingProxyType({"font_name": "Arial", "font_size": 10})
-
-    A_CTR = MappingProxyType({"align": "center"})
-    A_CTR_ACROSS = MappingProxyType({"align": "center_across"})
-    A_LEFT = MappingProxyType({"align": "left"})
-    A_RIGHT = MappingProxyType({"align": "right"})
-
-    BOLD = MappingProxyType({"bold": True})
-    ITALIC = MappingProxyType({"italic": True})
-    ULINE = MappingProxyType({"underline": True})
-
-    TEXT_WRAP = MappingProxyType({"text_wrap": True})
-    IND_1 = MappingProxyType({"indent": 1})
-
-    DOLLAR_NUM = MappingProxyType({"num_format": "[$$-409]#,##0.00"})
-    DT_NUM = MappingProxyType({"num_format": "mm/dd/yyyy"})
-    QTY_NUM = MappingProxyType({"num_format": "#,##0.0"})
-    PCT_NUM = MappingProxyType({"num_format": "##0.000000%"})
-    AREA_NUM = MappingProxyType({"num_format": "0.00000000"})
-
-    BAR_FILL = MappingProxyType({"pattern": 1, "bg_color": "dfeadf"})
-    BOT_BORDER = MappingProxyType({"bottom": 1, "bottom_color": "000000"})
-    TOP_BORDER = MappingProxyType({"top": 1, "top_color": "000000"})
-    HDR_BORDER = TOP_BORDER | BOT_BORDER
-
-
-def matrix_to_sheet(
-    _xl_book: xlsxwriter.workbook.Workbook,
-    _xl_sheet: xlsxwriter.worksheet.Worksheet,
-    _data_table: npt.ArrayLike,
-    _row_id: int,
-    _col_id: int = 0,
-    /,
-    *,
-    cell_format: Sequence[CFmt] | CFmt | None = None,
-    green_bar_flag: bool = True,
-) -> tuple[int, int]:
-    """
-    Write a 2-D array to a worksheet.
-
-    The given array is required be a two-dimensional array, whether
-    a nested list, nested tuple, or a 2-D numpy ndarray.
-
-    Parameters
-    ----------
-    _xl_book
-        Workbook object
-
-    _xl_sheet
-        Worksheet object to which to write the give array
-
-    _data_table
-        Array to be written
-
-    _row_id
-        Row number of top left corner of range to write to
-
-    _col_id
-        Column number of top left corner of range to write to
-
-    cell_format
-        Format specification for range to be written
-
-    green_bar_flag
-        Whether to highlight alternating rows as in green bar paper
-
-    Returns
-    -------
-        Tuple giving address of cell (at left) below range written
-
-    """
-    _data_array: npt.NDArray[Any] = np.array(_data_table)
-    del _data_table
-
-    if not len(_data_array.shape) == 2:
-        raise ValueError(
-            "Array to write must be a 2-D array, but"
-            f"the given array has shape, {_data_array.shape}."
-        )
-
-    # Get the array dimensions and row and column numbers for Excel
-    _bottom_row_id: int = _row_id + _data_array.shape[0]
-    _right_column_id: int = _col_id + _data_array.shape[1]
-
-    if isinstance(cell_format, tuple):
-        ensure_cell_format_spec_tuple(cell_format)
-        if not len(cell_format) == len(_data_array[0]):
-            raise ValueError("Format tuple does not match data in length.")
-        _cell_format: Sequence[CFmt] = cell_format
-    elif isinstance(cell_format, CFmt):
-        _cell_format = (cell_format,) * len(_data_array[0])
-    else:
-        _cell_format = (CFmt.XL_DEFAULT,) * len(_data_array[0])
-
-    for _cell_row in range(_row_id, _bottom_row_id):
-        for _cell_col in range(_col_id, _right_column_id):
-            _cell_fmt = (
-                (_cell_format[_cell_col - _col_id], CFmt.BAR_FILL)
-                if green_bar_flag and (_cell_row - _row_id) % 2
-                else _cell_format[_cell_col - _col_id]
-            )
-
-            scalar_to_sheet(
-                _xl_book,
-                _xl_sheet,
-                _cell_row,
-                _cell_col,
-                _data_array[_cell_row - _row_id, _cell_col - _col_id],
-                _cell_fmt,
-            )
-
-    return _bottom_row_id, _right_column_id
-
-
-def scalar_to_sheet(
-    _xl_book: xlsxwriter.workbook.Workbook,
-    _xl_sheet: xlsxwriter.worksheet.Worksheet,
-    _cell_addr_0: str | int | float = "A1",
-    /,
-    *_s2s_args: Any,
-) -> None:
-    """
-    Write to a single cell in a worksheet.
-
-    Parameters
-    ----------
-    _xl_book
-        Workbook object
-
-    _xl_sheet
-        Worksheet object to which to write the give array
-
-    _cell_addr_0
-        First element of a cell address, which may be the entire address
-        in 'A1' format or the row-part in 'R1,C1' format
-
-    _s2s_args
-        Other arguments, which may be just the cell value to be written and the
-        cell format, or the column-part of the 'R1,C1' address along with
-        cell value and cell format.
-
-    """
-
-    if isinstance(_cell_addr_0, str):
-        if len(_s2s_args) not in (1, 2):
-            raise ValueError("Too many or too few arguments.")
-        _cell_addr: tuple[int | str, ...] = (_cell_addr_0,)
-        _cell_val: Any = _s2s_args[0]
-        _cell_fmt: CFmt | Sequence[CFmt] = _s2s_args[1] if len(_s2s_args) == 2 else None  # type: ignore
-    elif isinstance(_cell_addr_0, int):
-        if len(_s2s_args) not in (2, 3):
-            raise ValueError("Too many or too few arguments.")
-        _cell_addr = (_cell_addr_0, _s2s_args[0])
-        _cell_val = _s2s_args[1]
-        _cell_fmt = _s2s_args[2] if len(_s2s_args) == 3 else None  # type: ignore
-    else:
-        raise ValueError("Incorrect specification for Excel cell data.")
-
-    _xl_sheet.write(*_cell_addr, _cell_val, xl_fmt(_xl_book, _cell_fmt))
-
-
-def xl_fmt(
-    _xl_book: xlsxwriter.Workbook, _cell_fmt: Sequence[CFmt] | CFmt | None, /
-) -> xlsxwriter.format.Format:
-    """
-    Return :code:`xlsxwriter` `Format` object given a CFmt enum, or tuple thereof.
-
-    Parameters
-    ----------
-    _xl_book
-        :code:`xlsxwriter.Workbook` object
-
-    _cell_fmt
-        :code:`CFmt` enum object, or tuple thereof
-
-    Returns
-    -------
-        :code:`xlsxwriter` `Format`  object
-
-    """
-    _cell_fmt_dict: Mapping[str, Any] = MappingProxyType({})
-    if isinstance(_cell_fmt, tuple):
-        ensure_cell_format_spec_tuple(_cell_fmt)
-        for _cf in _cell_fmt:
-            _cell_fmt_dict = _cell_fmt_dict | _cf.value
-    elif isinstance(_cell_fmt, CFmt):
-        _cell_fmt_dict = _cell_fmt.value
-    else:
-        _cell_fmt_dict = CFmt.XL_DEFAULT.value
-
-    return _xl_book.add_format(_cell_fmt_dict)
-
-
-def ensure_cell_format_spec_tuple(_cell_formats: Sequence[CFmt], /) -> None:
-    """
-    Test that a given format specification is tuple of CFmt enums
-
-    Parameters
-    ----------
-    _cell_formats
-        Format specification
-
-    Returns
-    -------
-        True if format specification passes, else False
-
-    """
-
-    for _cell_format in _cell_formats:
-        if isinstance(_cell_format, tuple):
-            ensure_cell_format_spec_tuple(_cell_format)
-
-        if not (isinstance(_cell_format, CFmt),):
-            raise ValueError("Improperly specified format tuple.")