From 3ad30c5ead4a5b46cadf50c02311c76c00e75899 Mon Sep 17 00:00:00 2001 From: Cristiano Date: Sat, 16 Dec 2023 15:19:09 +0000 Subject: [PATCH 1/4] docs: add documentation to xml conftest file fixtures Co-authored-by: GeorgeJuniorGG Co-authored-by: MylenaRoberta --- pandas/tests/io/xml/conftest.py | 61 +++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/pandas/tests/io/xml/conftest.py b/pandas/tests/io/xml/conftest.py index aafda0ff62bbd..9b53f12066fa4 100644 --- a/pandas/tests/io/xml/conftest.py +++ b/pandas/tests/io/xml/conftest.py @@ -5,34 +5,95 @@ @pytest.fixture def xml_data_path(): + """ + Returns a Path object to the XML example directory. + + Examples + -------- + >>> xsl_file = xml_data_path / "file.xsl" + >>> file = read_xml(xsl_file, stylesheet=xsl) + """ return Path(__file__).parent.parent / "data" / "xml" @pytest.fixture def xml_books(xml_data_path, datapath): + """ + Returns the path (as str) to the books.xml example file. + + Examples + -------- + >>> books_file = read_xml(xml_books, parser=parser) + """ return datapath(xml_data_path / "books.xml") @pytest.fixture def xml_doc_ch_utf(xml_data_path, datapath): + """ + Returns the path (as str) to the doc_ch_utf.xml example file. + + Examples + -------- + >>> doc_ch_utf_file = read_xml(xml_doc_ch_utf, parser=parser) + """ return datapath(xml_data_path / "doc_ch_utf.xml") @pytest.fixture def xml_baby_names(xml_data_path, datapath): + """ + Returns the path (as str) to the baby_names.xml example file. + + Examples + -------- + >>> baby_names_file = read_xml(xml_baby_names, parser=parser) + """ return datapath(xml_data_path / "baby_names.xml") @pytest.fixture def kml_cta_rail_lines(xml_data_path, datapath): + """ + Returns the path (as str) to the cta_rail_lines.kml example file. + + Examples + -------- + >>> cta_rail_lines_file = read_xml( + kml_cta_rail_lines, + xpath=".//k:Placemark", + namespaces={"k": "http://www.opengis.net/kml/2.2"}, + stylesheet=xsl_flatten_doc, + ) + """ return datapath(xml_data_path / "cta_rail_lines.kml") @pytest.fixture def xsl_flatten_doc(xml_data_path, datapath): + """ + Returns the path (as str) to the flatten_doc.xsl example file. + + Examples + -------- + >>> with open( + xsl_flatten_doc, mode, encoding="utf-8" if mode == "r" else None + ) as f: + xsl_obj = f.read() + """ return datapath(xml_data_path / "flatten_doc.xsl") @pytest.fixture def xsl_row_field_output(xml_data_path, datapath): + """ + Returns the path (as str) to the row_field_output.xsl example file. + + Examples + -------- + >>> with open( + xsl_row_field_output, mode, encoding="utf-8" if mode == "r" else None + ) as f: + xsl_obj = f.read() + """ return datapath(xml_data_path / "row_field_output.xsl") From 620a269357105dc0f66f61b17470eee69816f40d Mon Sep 17 00:00:00 2001 From: Cristiano Date: Sat, 16 Dec 2023 15:50:37 +0000 Subject: [PATCH 2/4] docs: add documentation to util conftest file fixtures Co-authored-by: GeorgeJuniorGG Co-authored-by: MylenaRoberta --- pandas/tests/util/conftest.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/pandas/tests/util/conftest.py b/pandas/tests/util/conftest.py index b68bcc93431d0..3224e174d426a 100644 --- a/pandas/tests/util/conftest.py +++ b/pandas/tests/util/conftest.py @@ -3,24 +3,44 @@ @pytest.fixture(params=[True, False]) def check_dtype(request): + """ + Fixture returning True or False, determining whether to check + if the Series dtype is identical or not. + """ return request.param @pytest.fixture(params=[True, False]) def check_exact(request): + """ + Fixture returning True or False, determining whether to + compare numbers exactly or not. + Comparison only takes effect for float dtypes. + """ return request.param @pytest.fixture(params=[True, False]) def check_index_type(request): + """ + Fixture returning True or False, determining whether to check + if the Index types are identical or not. + """ return request.param @pytest.fixture(params=[0.5e-3, 0.5e-5]) def rtol(request): + """ + Fixture returning 0.5e-3 or 0.5e-5. Those values are used as relative tolerance. + """ return request.param @pytest.fixture(params=[True, False]) def check_categorical(request): + """ + Fixture returning True or False, determining whether to + compare internal Categorical exactly or not. + """ return request.param From 656b5fabaa83d996b26c6a5cb295d2fa6328be40 Mon Sep 17 00:00:00 2001 From: Cristiano Date: Sat, 16 Dec 2023 17:39:27 +0000 Subject: [PATCH 3/4] docs: add documentation to pandas conftest arrow_string_storage fixture Co-authored-by: GeorgeJuniorGG Co-authored-by: MylenaRoberta --- pandas/conftest.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pandas/conftest.py b/pandas/conftest.py index 7c829ed4b8cb9..023bc54ec9bc6 100644 --- a/pandas/conftest.py +++ b/pandas/conftest.py @@ -1934,4 +1934,7 @@ def warsaw(request) -> str: @pytest.fixture() def arrow_string_storage(): + """ + Fixture that lists possible PyArrow values for StringDtype storage field. + """ return ("pyarrow", "pyarrow_numpy") From 52d7d5cbb8cb22e91fc12225fcbbfb253e33e15a Mon Sep 17 00:00:00 2001 From: Cristiano Date: Tue, 19 Dec 2023 00:11:59 +0000 Subject: [PATCH 4/4] doc: apply suggestions Co-authored-by: GeorgeJuniorGG Co-authored-by: MylenaRoberta --- pandas/tests/io/xml/conftest.py | 56 ++++++++++++++++++--------------- pandas/tests/util/conftest.py | 18 +++++------ 2 files changed, 40 insertions(+), 34 deletions(-) diff --git a/pandas/tests/io/xml/conftest.py b/pandas/tests/io/xml/conftest.py index 9b53f12066fa4..273b1a3beef3b 100644 --- a/pandas/tests/io/xml/conftest.py +++ b/pandas/tests/io/xml/conftest.py @@ -10,8 +10,8 @@ def xml_data_path(): Examples -------- - >>> xsl_file = xml_data_path / "file.xsl" - >>> file = read_xml(xsl_file, stylesheet=xsl) + >>> def test_read_xml(xml_data_path): + ... read_xml(xml_data_path / 'file.xsl') """ return Path(__file__).parent.parent / "data" / "xml" @@ -19,11 +19,12 @@ def xml_data_path(): @pytest.fixture def xml_books(xml_data_path, datapath): """ - Returns the path (as str) to the books.xml example file. + Returns the path (as `str`) to the `books.xml` example file. Examples -------- - >>> books_file = read_xml(xml_books, parser=parser) + >>> def test_read_xml(xml_books): + ... read_xml(xml_books) """ return datapath(xml_data_path / "books.xml") @@ -31,11 +32,12 @@ def xml_books(xml_data_path, datapath): @pytest.fixture def xml_doc_ch_utf(xml_data_path, datapath): """ - Returns the path (as str) to the doc_ch_utf.xml example file. + Returns the path (as `str`) to the `doc_ch_utf.xml` example file. Examples -------- - >>> doc_ch_utf_file = read_xml(xml_doc_ch_utf, parser=parser) + >>> def test_read_xml(xml_doc_ch_utf): + ... read_xml(xml_doc_ch_utf) """ return datapath(xml_data_path / "doc_ch_utf.xml") @@ -43,11 +45,12 @@ def xml_doc_ch_utf(xml_data_path, datapath): @pytest.fixture def xml_baby_names(xml_data_path, datapath): """ - Returns the path (as str) to the baby_names.xml example file. + Returns the path (as `str`) to the `baby_names.xml` example file. Examples -------- - >>> baby_names_file = read_xml(xml_baby_names, parser=parser) + >>> def test_read_xml(xml_baby_names): + ... read_xml(xml_baby_names) """ return datapath(xml_data_path / "baby_names.xml") @@ -55,16 +58,17 @@ def xml_baby_names(xml_data_path, datapath): @pytest.fixture def kml_cta_rail_lines(xml_data_path, datapath): """ - Returns the path (as str) to the cta_rail_lines.kml example file. + Returns the path (as `str`) to the `cta_rail_lines.kml` example file. Examples -------- - >>> cta_rail_lines_file = read_xml( - kml_cta_rail_lines, - xpath=".//k:Placemark", - namespaces={"k": "http://www.opengis.net/kml/2.2"}, - stylesheet=xsl_flatten_doc, - ) + >>> def test_read_xml(kml_cta_rail_lines): + ... read_xml( + ... kml_cta_rail_lines, + ... xpath=".//k:Placemark", + ... namespaces={"k": "http://www.opengis.net/kml/2.2"}, + ... stylesheet=xsl_flatten_doc, + ... ) """ return datapath(xml_data_path / "cta_rail_lines.kml") @@ -72,14 +76,15 @@ def kml_cta_rail_lines(xml_data_path, datapath): @pytest.fixture def xsl_flatten_doc(xml_data_path, datapath): """ - Returns the path (as str) to the flatten_doc.xsl example file. + Returns the path (as `str`) to the `flatten_doc.xsl` example file. Examples -------- - >>> with open( - xsl_flatten_doc, mode, encoding="utf-8" if mode == "r" else None - ) as f: - xsl_obj = f.read() + >>> def test_read_xsl(xsl_flatten_doc): + ... with open( + ... xsl_flatten_doc, mode, encoding="utf-8" if mode == "r" else None + ... ) as f: + ... xsl_obj = f.read() """ return datapath(xml_data_path / "flatten_doc.xsl") @@ -87,13 +92,14 @@ def xsl_flatten_doc(xml_data_path, datapath): @pytest.fixture def xsl_row_field_output(xml_data_path, datapath): """ - Returns the path (as str) to the row_field_output.xsl example file. + Returns the path (as `str`) to the `row_field_output.xsl` example file. Examples -------- - >>> with open( - xsl_row_field_output, mode, encoding="utf-8" if mode == "r" else None - ) as f: - xsl_obj = f.read() + >>> def test_read_xsl(xsl_row_field_output): + ... with open( + ... xsl_row_field_output, mode, encoding="utf-8" if mode == "r" else None + ... ) as f: + ... xsl_obj = f.read() """ return datapath(xml_data_path / "row_field_output.xsl") diff --git a/pandas/tests/util/conftest.py b/pandas/tests/util/conftest.py index 3224e174d426a..2e931ff42fe15 100644 --- a/pandas/tests/util/conftest.py +++ b/pandas/tests/util/conftest.py @@ -4,8 +4,9 @@ @pytest.fixture(params=[True, False]) def check_dtype(request): """ - Fixture returning True or False, determining whether to check - if the Series dtype is identical or not. + Fixture returning `True` or `False`, determining whether to check + if the `dtype` is identical or not, when comparing two data structures, + e.g. `Series`, `SparseArray` or `DataFrame`. """ return request.param @@ -13,9 +14,8 @@ def check_dtype(request): @pytest.fixture(params=[True, False]) def check_exact(request): """ - Fixture returning True or False, determining whether to - compare numbers exactly or not. - Comparison only takes effect for float dtypes. + Fixture returning `True` or `False`, determining whether to + compare floating point numbers exactly or not. """ return request.param @@ -23,8 +23,8 @@ def check_exact(request): @pytest.fixture(params=[True, False]) def check_index_type(request): """ - Fixture returning True or False, determining whether to check - if the Index types are identical or not. + Fixture returning `True` or `False`, determining whether to check + if the `Index` types are identical or not. """ return request.param @@ -40,7 +40,7 @@ def rtol(request): @pytest.fixture(params=[True, False]) def check_categorical(request): """ - Fixture returning True or False, determining whether to - compare internal Categorical exactly or not. + Fixture returning `True` or `False`, determining whether to + compare internal `Categorical` exactly or not. """ return request.param