[ENH] pivot_longer_spec (#1362)

* implement pivot_longer_spec

* add tests for pivot_longer_spec

* improve perf for sort_by_appearance, general refactor, added docs to pivot_longer_spec

* changelog

* minor changes

* missing comma in docs

* ensure .value position in pivot_longer_spec

* use nunique instead of len(arr.unique)

* handle duplicated columns in pivot_longer_spec

* add more descriptions in the docs on the relevance of pivot_longer_spec

* pivot_longer_spec

* remove irrelevant files

* remove irrelevant files

* typo

* fix failing tests

* add check for spec dataframe

* explicit positions in pivot_longer_spec

* use future annotations

* change approach to transformation

* create function for dropna

* fix docs

* changelog

---------

Co-authored-by: samuel.oranyeli <samuel.oranyeli@grow.inc>
Co-authored-by: Eric Ma <ericmjl@users.noreply.github.com>

CHANGELOG.md

@@ -2,14 +2,17 @@
 
 ## [Unreleased]
 
+
+- [ENH] Improve `pivot_longer` when `sort_by_appearance` is True. Added `pivot_longer_spec` for more control on how the dataframe should be unpivoted. -@samukweku #1361
 - [ENH] Added `convert_excel_date` and `convert_matlab_date` methods for polars - Issue #1352
 - [ENH] Added a `complete` method for polars. - Issue #1352 @samukweku
-- [ENH] `read_commandline` function now supports polars - Issue #1352
-- [ENH] Improved performance for non-equi joins when using numba - @samukweku PR #1341
-- [ENH] Added a `clean_names` method for polars - it can be used to clean the column names, or clean column values . Issue #1343 @samukweku
+- [ENH] Added a `pivot_longer` method, and a `pivot_longer_spec` function for polars - Issue #1352 @samukweku
+- [ENH] Added a `row_to_names` method for polars. Issue #1352 @samukweku
+- [ENH] `read_commandline` function now supports polars - Issue #1352 @samukweku
 - [ENH] `xlsx_cells` function now supports polars - Issue #1352 @samukweku
 - [ENH] `xlsx_table` function now supports polars - Issue #1352 @samukweku
-- [ENH] Added a `pivot_longer` method, and a `pivot_longer_spec` function for polars - Issue #1352 @samukweku
+- [ENH] Added a `clean_names` method for polars - it can be used to clean the column names, or clean column values . Issue #1343 @samukweku
+- [ENH] Improved performance for non-equi joins when using numba - @samukweku PR #1341
 - [ENH] pandas Index,Series, DataFrame now supported in the `complete` method. - PR #1369 @samukweku
 
 ## [v0.27.0] - 2024-03-21

janitor/functions/__init__.py

@@ -57,7 +57,7 @@
 from .limit_column_characters import limit_column_characters
 from .min_max_scale import min_max_scale
 from .move import move
-from .pivot import pivot_longer, pivot_wider
+from .pivot import pivot_longer, pivot_longer_spec, pivot_wider
 from .process_text import process_text
 from .remove_columns import remove_columns
 from .remove_empty import remove_empty
@@ -132,6 +132,7 @@
     "min_max_scale",
     "move",
     "pivot_longer",
+    "pivot_longer_spec",
     "pivot_wider",
     "process_text",
     "remove_columns",