Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/pandas/errors/__init__.py: 87%
54 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1"""
2Expose public exceptions & warnings
3"""
4from __future__ import annotations
6import ctypes
8from pandas._config.config import OptionError
10from pandas._libs.tslibs import (
11 OutOfBoundsDatetime,
12 OutOfBoundsTimedelta,
13)
16class IntCastingNaNError(ValueError):
17 """
18 Exception raised when converting (``astype``) an array with NaN to an integer type.
19 """
22class NullFrequencyError(ValueError):
23 """
24 Exception raised when a ``freq`` cannot be null.
26 Particularly ``DatetimeIndex.shift``, ``TimedeltaIndex.shift``,
27 ``PeriodIndex.shift``.
28 """
31class PerformanceWarning(Warning):
32 """
33 Warning raised when there is a possible performance impact.
34 """
37class UnsupportedFunctionCall(ValueError):
38 """
39 Exception raised when attempting to call a unsupported numpy function.
41 For example, ``np.cumsum(groupby_object)``.
42 """
45class UnsortedIndexError(KeyError):
46 """
47 Error raised when slicing a MultiIndex which has not been lexsorted.
49 Subclass of `KeyError`.
50 """
53class ParserError(ValueError):
54 """
55 Exception that is raised by an error encountered in parsing file contents.
57 This is a generic error raised for errors encountered when functions like
58 `read_csv` or `read_html` are parsing contents of a file.
60 See Also
61 --------
62 read_csv : Read CSV (comma-separated) file into a DataFrame.
63 read_html : Read HTML table into a DataFrame.
64 """
67class DtypeWarning(Warning):
68 """
69 Warning raised when reading different dtypes in a column from a file.
71 Raised for a dtype incompatibility. This can happen whenever `read_csv`
72 or `read_table` encounter non-uniform dtypes in a column(s) of a given
73 CSV file.
75 See Also
76 --------
77 read_csv : Read CSV (comma-separated) file into a DataFrame.
78 read_table : Read general delimited file into a DataFrame.
80 Notes
81 -----
82 This warning is issued when dealing with larger files because the dtype
83 checking happens per chunk read.
85 Despite the warning, the CSV file is read with mixed types in a single
86 column which will be an object type. See the examples below to better
87 understand this issue.
89 Examples
90 --------
91 This example creates and reads a large CSV file with a column that contains
92 `int` and `str`.
94 >>> df = pd.DataFrame({'a': (['1'] * 100000 + ['X'] * 100000 +
95 ... ['1'] * 100000),
96 ... 'b': ['b'] * 300000}) # doctest: +SKIP
97 >>> df.to_csv('test.csv', index=False) # doctest: +SKIP
98 >>> df2 = pd.read_csv('test.csv') # doctest: +SKIP
99 ... # DtypeWarning: Columns (0) have mixed types
101 Important to notice that ``df2`` will contain both `str` and `int` for the
102 same input, '1'.
104 >>> df2.iloc[262140, 0] # doctest: +SKIP
105 '1'
106 >>> type(df2.iloc[262140, 0]) # doctest: +SKIP
107 <class 'str'>
108 >>> df2.iloc[262150, 0] # doctest: +SKIP
109 1
110 >>> type(df2.iloc[262150, 0]) # doctest: +SKIP
111 <class 'int'>
113 One way to solve this issue is using the `dtype` parameter in the
114 `read_csv` and `read_table` functions to explicit the conversion:
116 >>> df2 = pd.read_csv('test.csv', sep=',', dtype={'a': str}) # doctest: +SKIP
118 No warning was issued.
119 """
122class EmptyDataError(ValueError):
123 """
124 Exception raised in ``pd.read_csv`` when empty data or header is encountered.
125 """
128class ParserWarning(Warning):
129 """
130 Warning raised when reading a file that doesn't use the default 'c' parser.
132 Raised by `pd.read_csv` and `pd.read_table` when it is necessary to change
133 parsers, generally from the default 'c' parser to 'python'.
135 It happens due to a lack of support or functionality for parsing a
136 particular attribute of a CSV file with the requested engine.
138 Currently, 'c' unsupported options include the following parameters:
140 1. `sep` other than a single character (e.g. regex separators)
141 2. `skipfooter` higher than 0
142 3. `sep=None` with `delim_whitespace=False`
144 The warning can be avoided by adding `engine='python'` as a parameter in
145 `pd.read_csv` and `pd.read_table` methods.
147 See Also
148 --------
149 pd.read_csv : Read CSV (comma-separated) file into DataFrame.
150 pd.read_table : Read general delimited file into DataFrame.
152 Examples
153 --------
154 Using a `sep` in `pd.read_csv` other than a single character:
156 >>> import io
157 >>> csv = '''a;b;c
158 ... 1;1,8
159 ... 1;2,1'''
160 >>> df = pd.read_csv(io.StringIO(csv), sep='[;,]') # doctest: +SKIP
161 ... # ParserWarning: Falling back to the 'python' engine...
163 Adding `engine='python'` to `pd.read_csv` removes the Warning:
165 >>> df = pd.read_csv(io.StringIO(csv), sep='[;,]', engine='python')
166 """
169class MergeError(ValueError):
170 """
171 Exception raised when merging data.
173 Subclass of ``ValueError``.
174 """
177class AccessorRegistrationWarning(Warning):
178 """
179 Warning for attribute conflicts in accessor registration.
180 """
183class AbstractMethodError(NotImplementedError):
184 """
185 Raise this error instead of NotImplementedError for abstract methods.
186 """
188 def __init__(self, class_instance, methodtype: str = "method") -> None:
189 types = {"method", "classmethod", "staticmethod", "property"}
190 if methodtype not in types:
191 raise ValueError(
192 f"methodtype must be one of {methodtype}, got {types} instead."
193 )
194 self.methodtype = methodtype
195 self.class_instance = class_instance
197 def __str__(self) -> str:
198 if self.methodtype == "classmethod":
199 name = self.class_instance.__name__
200 else:
201 name = type(self.class_instance).__name__
202 return f"This {self.methodtype} must be defined in the concrete class {name}"
205class NumbaUtilError(Exception):
206 """
207 Error raised for unsupported Numba engine routines.
208 """
211class DuplicateLabelError(ValueError):
212 """
213 Error raised when an operation would introduce duplicate labels.
215 .. versionadded:: 1.2.0
217 Examples
218 --------
219 >>> s = pd.Series([0, 1, 2], index=['a', 'b', 'c']).set_flags(
220 ... allows_duplicate_labels=False
221 ... )
222 >>> s.reindex(['a', 'a', 'b'])
223 Traceback (most recent call last):
224 ...
225 DuplicateLabelError: Index has duplicates.
226 positions
227 label
228 a [0, 1]
229 """
232class InvalidIndexError(Exception):
233 """
234 Exception raised when attempting to use an invalid index key.
236 .. versionadded:: 1.1.0
237 """
240class DataError(Exception):
241 """
242 Exceptionn raised when performing an operation on non-numerical data.
244 For example, calling ``ohlc`` on a non-numerical column or a function
245 on a rolling window.
246 """
249class SpecificationError(Exception):
250 """
251 Exception raised by ``agg`` when the functions are ill-specified.
253 The exception raised in two scenarios.
255 The first way is calling ``agg`` on a
256 Dataframe or Series using a nested renamer (dict-of-dict).
258 The second way is calling ``agg`` on a Dataframe with duplicated functions
259 names without assigning column name.
261 Examples
262 --------
263 >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2],
264 ... 'B': range(5),
265 ... 'C': range(5)})
266 >>> df.groupby('A').B.agg({'foo': 'count'}) # doctest: +SKIP
267 ... # SpecificationError: nested renamer is not supported
269 >>> df.groupby('A').agg({'B': {'foo': ['sum', 'max']}}) # doctest: +SKIP
270 ... # SpecificationError: nested renamer is not supported
272 >>> df.groupby('A').agg(['min', 'min']) # doctest: +SKIP
273 ... # SpecificationError: nested renamer is not supported
274 """
277class SettingWithCopyError(ValueError):
278 """
279 Exception raised when trying to set on a copied slice from a ``DataFrame``.
281 The ``mode.chained_assignment`` needs to be set to set to 'raise.' This can
282 happen unintentionally when chained indexing.
284 For more information on eveluation order,
285 see :ref:`the user guide<indexing.evaluation_order>`.
287 For more information on view vs. copy,
288 see :ref:`the user guide<indexing.view_versus_copy>`.
290 Examples
291 --------
292 >>> pd.options.mode.chained_assignment = 'raise'
293 >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
294 >>> df.loc[0:3]['A'] = 'a' # doctest: +SKIP
295 ... # SettingWithCopyError: A value is trying to be set on a copy of a...
296 """
299class SettingWithCopyWarning(Warning):
300 """
301 Warning raised when trying to set on a copied slice from a ``DataFrame``.
303 The ``mode.chained_assignment`` needs to be set to set to 'warn.'
304 'Warn' is the default option. This can happen unintentionally when
305 chained indexing.
307 For more information on eveluation order,
308 see :ref:`the user guide<indexing.evaluation_order>`.
310 For more information on view vs. copy,
311 see :ref:`the user guide<indexing.view_versus_copy>`.
313 Examples
314 --------
315 >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
316 >>> df.loc[0:3]['A'] = 'a' # doctest: +SKIP
317 ... # SettingWithCopyWarning: A value is trying to be set on a copy of a...
318 """
321class NumExprClobberingError(NameError):
322 """
323 Exception raised when trying to use a built-in numexpr name as a variable name.
325 ``eval`` or ``query`` will throw the error if the engine is set
326 to 'numexpr'. 'numexpr' is the default engine value for these methods if the
327 numexpr package is installed.
329 Examples
330 --------
331 >>> df = pd.DataFrame({'abs': [1, 1, 1]})
332 >>> df.query("abs > 2") # doctest: +SKIP
333 ... # NumExprClobberingError: Variables in expression "(abs) > (2)" overlap...
334 >>> sin, a = 1, 2
335 >>> pd.eval("sin + a", engine='numexpr') # doctest: +SKIP
336 ... # NumExprClobberingError: Variables in expression "(sin) + (a)" overlap...
337 """
340class UndefinedVariableError(NameError):
341 """
342 Exception raised by ``query`` or ``eval`` when using an undefined variable name.
344 It will also specify whether the undefined variable is local or not.
346 Examples
347 --------
348 >>> df = pd.DataFrame({'A': [1, 1, 1]})
349 >>> df.query("A > x") # doctest: +SKIP
350 ... # UndefinedVariableError: name 'x' is not defined
351 >>> df.query("A > @y") # doctest: +SKIP
352 ... # UndefinedVariableError: local variable 'y' is not defined
353 >>> pd.eval('x + 1') # doctest: +SKIP
354 ... # UndefinedVariableError: name 'x' is not defined
355 """
357 def __init__(self, name: str, is_local: bool | None = None) -> None:
358 base_msg = f"{repr(name)} is not defined"
359 if is_local:
360 msg = f"local variable {base_msg}"
361 else:
362 msg = f"name {base_msg}"
363 super().__init__(msg)
366class IndexingError(Exception):
367 """
368 Exception is raised when trying to index and there is a mismatch in dimensions.
370 Examples
371 --------
372 >>> df = pd.DataFrame({'A': [1, 1, 1]})
373 >>> df.loc[..., ..., 'A'] # doctest: +SKIP
374 ... # IndexingError: indexer may only contain one '...' entry
375 >>> df = pd.DataFrame({'A': [1, 1, 1]})
376 >>> df.loc[1, ..., ...] # doctest: +SKIP
377 ... # IndexingError: Too many indexers
378 >>> df[pd.Series([True], dtype=bool)] # doctest: +SKIP
379 ... # IndexingError: Unalignable boolean Series provided as indexer...
380 >>> s = pd.Series(range(2),
381 ... index = pd.MultiIndex.from_product([["a", "b"], ["c"]]))
382 >>> s.loc["a", "c", "d"] # doctest: +SKIP
383 ... # IndexingError: Too many indexers
384 """
387class PyperclipException(RuntimeError):
388 """
389 Exception raised when clipboard functionality is unsupported.
391 Raised by ``to_clipboard()`` and ``read_clipboard()``.
392 """
395class PyperclipWindowsException(PyperclipException):
396 """
397 Exception raised when clipboard functionality is unsupported by Windows.
399 Access to the clipboard handle would be denied due to some other
400 window process is accessing it.
401 """
403 def __init__(self, message: str) -> None:
404 # attr only exists on Windows, so typing fails on other platforms
405 message += f" ({ctypes.WinError()})" # type: ignore[attr-defined]
406 super().__init__(message)
409class CSSWarning(UserWarning):
410 """
411 Warning is raised when converting css styling fails.
413 This can be due to the styling not having an equivalent value or because the
414 styling isn't properly formatted.
416 Examples
417 --------
418 >>> df = pd.DataFrame({'A': [1, 1, 1]})
419 >>> df.style.applymap(lambda x: 'background-color: blueGreenRed;')
420 ... .to_excel('styled.xlsx') # doctest: +SKIP
421 ... # CSSWarning: Unhandled color format: 'blueGreenRed'
422 >>> df.style.applymap(lambda x: 'border: 1px solid red red;')
423 ... .to_excel('styled.xlsx') # doctest: +SKIP
424 ... # CSSWarning: Too many tokens provided to "border" (expected 1-3)
425 """
428class PossibleDataLossError(Exception):
429 """
430 Exception raised when trying to open a HDFStore file when already opened.
432 Examples
433 --------
434 >>> store = pd.HDFStore('my-store', 'a') # doctest: +SKIP
435 >>> store.open("w") # doctest: +SKIP
436 ... # PossibleDataLossError: Re-opening the file [my-store] with mode [a]...
437 """
440class ClosedFileError(Exception):
441 """
442 Exception is raised when trying to perform an operation on a closed HDFStore file.
444 Examples
445 --------
446 >>> store = pd.HDFStore('my-store', 'a') # doctest: +SKIP
447 >>> store.close() # doctest: +SKIP
448 >>> store.keys() # doctest: +SKIP
449 ... # ClosedFileError: my-store file is not open!
450 """
453class IncompatibilityWarning(Warning):
454 """
455 Warning raised when trying to use where criteria on an incompatible HDF5 file.
456 """
459class AttributeConflictWarning(Warning):
460 """
461 Warning raised when index attributes conflict when using HDFStore.
463 Occurs when attempting to append an index with a different
464 name than the existing index on an HDFStore or attempting to append an index with a
465 different frequency than the existing index on an HDFStore.
466 """
469class DatabaseError(OSError):
470 """
471 Error is raised when executing sql with bad syntax or sql that throws an error.
473 Examples
474 --------
475 >>> from sqlite3 import connect
476 >>> conn = connect(':memory:')
477 >>> pd.read_sql('select * test', conn) # doctest: +SKIP
478 ... # DatabaseError: Execution failed on sql 'test': near "test": syntax error
479 """
482class PossiblePrecisionLoss(Warning):
483 """
484 Warning raised by to_stata on a column with a value outside or equal to int64.
486 When the column value is outside or equal to the int64 value the column is
487 converted to a float64 dtype.
489 Examples
490 --------
491 >>> df = pd.DataFrame({"s": pd.Series([1, 2**53], dtype=np.int64)})
492 >>> df.to_stata('test') # doctest: +SKIP
493 ... # PossiblePrecisionLoss: Column converted from int64 to float64...
494 """
497class ValueLabelTypeMismatch(Warning):
498 """
499 Warning raised by to_stata on a category column that contains non-string values.
501 Examples
502 --------
503 >>> df = pd.DataFrame({"categories": pd.Series(["a", 2], dtype="category")})
504 >>> df.to_stata('test') # doctest: +SKIP
505 ... # ValueLabelTypeMismatch: Stata value labels (pandas categories) must be str...
506 """
509class InvalidColumnName(Warning):
510 """
511 Warning raised by to_stata the column contains a non-valid stata name.
513 Because the column name is an invalid Stata variable, the name needs to be
514 converted.
516 Examples
517 --------
518 >>> df = pd.DataFrame({"0categories": pd.Series([2, 2])})
519 >>> df.to_stata('test') # doctest: +SKIP
520 ... # InvalidColumnName: Not all pandas column names were valid Stata variable...
521 """
524class CategoricalConversionWarning(Warning):
525 """
526 Warning is raised when reading a partial labeled Stata file using a iterator.
528 Examples
529 --------
530 >>> from pandas.io.stata import StataReader
531 >>> with StataReader('dta_file', chunksize=2) as reader: # doctest: +SKIP
532 ... for i, block in enumerate(reader):
533 ... print(i, block))
534 ... # CategoricalConversionWarning: One or more series with value labels...
535 """
538__all__ = [
539 "AbstractMethodError",
540 "AccessorRegistrationWarning",
541 "AttributeConflictWarning",
542 "CategoricalConversionWarning",
543 "ClosedFileError",
544 "CSSWarning",
545 "DatabaseError",
546 "DataError",
547 "DtypeWarning",
548 "DuplicateLabelError",
549 "EmptyDataError",
550 "IncompatibilityWarning",
551 "IntCastingNaNError",
552 "InvalidColumnName",
553 "InvalidIndexError",
554 "IndexingError",
555 "MergeError",
556 "NullFrequencyError",
557 "NumbaUtilError",
558 "NumExprClobberingError",
559 "OptionError",
560 "OutOfBoundsDatetime",
561 "OutOfBoundsTimedelta",
562 "ParserError",
563 "ParserWarning",
564 "PerformanceWarning",
565 "PossibleDataLossError",
566 "PossiblePrecisionLoss",
567 "PyperclipException",
568 "PyperclipWindowsException",
569 "SettingWithCopyError",
570 "SettingWithCopyWarning",
571 "SpecificationError",
572 "UndefinedVariableError",
573 "UnsortedIndexError",
574 "UnsupportedFunctionCall",
575 "ValueLabelTypeMismatch",
576]