[ { "id": "django_gen_01", "repo": "django", "question": "What does the `check_string` function in GDAL's error-checking prototypes do, and what roles do its `str_result` and `offset` keyword arguments play?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The `check_string` function in django's GDAL prototypes serves two purposes: it checks the string output returned from a given function AND frees the string pointer that was allocated by OGR. It supports two modes of operation controlled by keyword arguments: (1) When `str_result` is used, the function's return value itself is treated as the string pointer; otherwise, the return value is assumed to be an OGR error code. (2) The `offset` keyword is used to extract a string pointer that was passed by-reference at a specific slice offset in the function arguments, rather than being returned directly.", "rubric": [ "Explains that check_string checks string output returned from a function and frees the string pointer allocated by OGR (using VSIFree)", "Explains that when str_result is True, the function's return value itself is treated as the string pointer", "Explains that when str_result is False (default), the return value is treated as an OGR error code and checked via check_err", "Explains that the offset keyword is used to extract the string pointer passed by-reference at a specific position in the function's C arguments" ], "key_files": [ "django/contrib/gis/gdal/prototypes/errcheck.py" ], "source_doc": "[docstring: django/contrib/gis/gdal/prototypes/errcheck.py] django.contrib.gis.gdal.prototypes.errcheck.check_string\nCheck the string output returned from the given function, and free\n the string pointer allocated by OGR. The `str_result` keyword\n may be used when the result is the string pointer, otherwise\n the OGR error code is assumed. The `offset` keyword may be used\n to extract the string pointer passed in by-reference at the given\n slice offset in the function arguments.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_03", "repo": "django", "question": "Where does GDALBand store and manage computed statistics, and how are empty bands and caching handled in that flow?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "For raster formats using Persistent Auxiliary Metadata (PAM) services, the statistics computed on a GDALBand might be cached in an auxiliary file. When all pixel values in a band are nodata (an empty band), all statistics values are returned as None rather than raising an error or returning zeros. Additionally, the _flush method on a GDALBand not only calls the flush method on the Band's parent raster but also forces a refresh of the statistics attribute when it is requested the next time. The statistics method returns a tuple structured as (minimum, maximum, mean, standard deviation), and the approximate parameter allows statistics to be computed based on overviews or a subset of image tiles rather than the full dataset.", "rubric": [ "Statistics may be cached in an auxiliary file for raster formats using Persistent Auxiliary Metadata (PAM) services", "For empty bands (all pixel values are nodata), all statistics values are returned as None (not an error or zeros)", "The _flush method calls the parent raster's flush method AND sets _stats_refresh to True, forcing a recomputation next time statistics is called", "The statistics method returns a tuple structured as (minimum, maximum, mean, standard deviation)", "The approximate parameter allows statistics to be computed based on overviews or a subset of image tiles rather than the full dataset" ], "key_files": [ "django/contrib/gis/gdal/raster/band.py" ], "source_doc": "[docstring: django/contrib/gis/gdal/raster/band.py] django.contrib.gis.gdal.raster.band.GDALBand\ndjango.contrib.gis.gdal.raster.band.GDALBand:\n Wrap a GDAL raster band, needs to be obtained from a GDALRaster object.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand._flush:\n Call the flush method on the Band's parent raster and force a refresh\n of the statistics attribute when requested the next time.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.description:\n Return the description string of the band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.width:\n Width (X axis) in pixels of the band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.height:\n Height (Y axis) in pixels of the band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.pixel_count:\n Return the total number of pixels in this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.statistics:\n Compute statistics on the pixel values of this band.\n\n The return value is a tuple with the following structure:\n (minimum, maximum, mean, standard deviation).\n\n If approximate=True, the statistics may be computed based on overviews\n or a subset of image tiles.\n\n If refresh=True, the statistics will be computed from the data\n directly, and the cache will be updated where applicable.\n\n For empty bands (where all pixel values are nodata), all statistics\n values are returned as None.\n\n For raster formats using Persistent Auxiliary Metadata (PAM) services,\n the statistics might be cached in an auxiliary file.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.min:\n Return the minimum pixel value for this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.max:\n Return the maximum pixel value for this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.mean:\n Return the mean of all pixel values of this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.std:\n Return the standard deviation of all pixel values of this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.nodata_value:\n Return the nodata value for this band, or None if it isn't set.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.nodata_value:\n Set the nodata value for this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.datatype:\n Return the GDAL Pixel Datatype for this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.color_interp:\n Return the GDAL color interpretation for this band.\n\ndjango.contrib.gis.gdal.raster.band.GDALBand.data:\n Read or writes pixel values for this band. Blocks of data can\n be accessed by specifying the width, height and offset of the\n desired block. The same specification can be used to update\n parts of a raster by providing an array of values.\n\n Allowed input data types are bytes, memoryview, list, tuple, and array.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_02", "repo": "django", "question": "Why does the `string_output` function have a `const` flag, and how does it relate to `str_result` and memory management?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The `const` flag in the `string_output` function controls whether the allocated pointer returned by the GDAL function should be freed using the GDAL library routine `VSIFree`. This design decision exists because GDAL functions that return strings may either return pointers to constant/internal strings (which should NOT be freed by the caller) or pointers to newly allocated memory (which MUST be freed to avoid memory leaks). The `const` flag only applies when `str_result` is True, meaning it only matters when the function is actually configured to return a string result from a GDAL pointer. When `const` is set appropriately, it tells the wrapper whether to call VSIFree on the returned pointer after extracting the string value, preventing both memory leaks (from not freeing allocated strings) and crashes (from freeing constant/internal string pointers).", "rubric": [ "Explains that the `const` flag controls whether the returned GDAL string pointer should be freed using VSIFree", "Notes that some GDAL functions return pointers to constant/internal strings that must NOT be freed, while others return newly allocated memory that MUST be freed", "States that the `const` flag only applies when `str_result` is True (i.e., when the function directly returns a string pointer rather than an error code)", "Explains that proper use of this flag prevents both memory leaks (not freeing allocated strings) and crashes (freeing constant/internal string pointers)" ], "key_files": [ "django/contrib/gis/gdal/prototypes/generation.py" ], "source_doc": "[docstring: django/contrib/gis/gdal/prototypes/generation.py] django.contrib.gis.gdal.prototypes.generation.string_output\nGenerate a ctypes prototype for the given function with the\n given argument types that returns a string from a GDAL pointer.\n The `const` flag indicates whether the allocated pointer should\n be freed via the GDAL library routine VSIFree -- but only applies\n only when `str_result` is True.", "verification_verdict": "warn", "verification_issues": [ "The answer states that when `const` is set appropriately, it tells the wrapper whether to call VSIFree on the returned pointer. However, the documentation says the `const` flag indicates whether the allocated pointer *should* be freed via VSIFree. The answer's interpretation that `const=True` means 'do NOT free' (constant/internal strings) is a plausible extrapolation but not explicitly stated in the documentation - the doc just says it 'indicates whether the allocated pointer should be freed'.", "The detailed explanation about preventing memory leaks and crashes is a reasonable extrapolation about the purpose of the flag, but these specifics are not directly stated in the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_04", "repo": "django", "question": "How does the GDALRaster's warp method construct and configure the target raster, including default parameters and naming?", "category": "how", "sub_type": "system_design", "gold_answer": "When the GDALRaster.warp() method is called, it operates as follows: It accepts a dictionary of target raster parameters including width, height, SRID, origin, scale, skew, datatype, driver, and name (filename). By default, all parameters remain equal to the values of the original source raster. For the target raster's name, if not specified, the source raster's name is used with '_copy.' appended followed by the source driver name. The resampling algorithm defaults to NearestNeighbor, and all available resampling options can be found in the GDAL_RESAMPLE_ALGORITHMS constant. Additionally, when the geotransform has not been set or does not exist, a default value of [0.0, 1.0, 0.0, 0.0, 0.0, -1.0] is returned. The _flush method automatically handles writing geotransforms, coordinate systems, nodata_values, and pixel values from memory to the source file, and is called automatically wherever needed.", "rubric": [ "Mentions that warp accepts a dictionary of target raster parameters (width, height, SRID, origin, scale, skew, datatype, driver, name)", "Explains that all parameters default to the source raster's values via setdefault", "Explains that the target name defaults to the source name appended with '_copy.' plus the source driver name", "States that the default resampling algorithm is NearestNeighbour and options come from GDAL_RESAMPLE_ALGORITHMS", "Mentions that the geotransform property returns a default of [0.0, 1.0, 0.0, 0.0, 0.0, -1.0] if not set", "Explains that _flush writes geotransforms, coordinate systems, nodata_values, and pixel values from memory to the source file and is called automatically" ], "key_files": [ "django/contrib/gis/gdal/raster/source.py" ], "source_doc": "[docstring: django/contrib/gis/gdal/raster/source.py] django.contrib.gis.gdal.raster.source.GDALRaster\ndjango.contrib.gis.gdal.raster.source.GDALRaster:\n Wrap a raster GDAL Data Source object.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.__repr__:\n Short-hand representation because WKB may be very large.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster._flush:\n Flush all data from memory into the source file if it exists.\n The data that needs flushing are geotransforms, coordinate systems,\n nodata_values and pixel values. This function will be called\n automatically wherever it is needed.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.name:\n Return the name of this raster. Corresponds to filename\n for file-based rasters.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.driver:\n Return the GDAL Driver used for this raster.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.width:\n Width (X axis) in pixels.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.height:\n Height (Y axis) in pixels.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.srs:\n Return the SpatialReference used in this GDALRaster.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.srs:\n Set the spatial reference used in this GDALRaster. The input can be\n a SpatialReference or any parameter accepted by the SpatialReference\n constructor.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.srid:\n Shortcut to access the srid of this GDALRaster.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.srid:\n Shortcut to set this GDALRaster's srs from an srid.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.geotransform:\n Return the geotransform of the data source.\n Return the default geotransform if it does not exist or has not been\n set previously. The default is [0.0, 1.0, 0.0, 0.0, 0.0, -1.0].\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.geotransform:\n Set the geotransform for the data source.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.origin:\n Coordinates of the raster origin.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.scale:\n Pixel scale in units of the raster projection.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.skew:\n Skew of pixels (rotation parameters).\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.extent:\n Return the extent as a 4-tuple (xmin, ymin, xmax, ymax).\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.warp:\n Return a warped GDALRaster with the given input characteristics.\n\n The input is expected to be a dictionary containing the parameters\n of the target raster. Allowed values are width, height, SRID, origin,\n scale, skew, datatype, driver, and name (filename).\n\n By default, the warp functions keeps all parameters equal to the values\n of the original source raster. For the name of the target raster, the\n name of the source raster will be used and appended with\n _copy. + source_driver_name.\n\n In addition, the resampling algorithm can be specified with the\n \"resampling\" input parameter. The default is NearestNeighbor. For a\n list of all options consult the GDAL_RESAMPLE_ALGORITHMS constant.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.clone:\n Return a clone of this GDALRaster.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.transform:\n Return a copy of this raster reprojected into the given spatial\n reference system.\n\ndjango.contrib.gis.gdal.raster.source.GDALRaster.info:\n Return information about this raster in a string format equivalent\n to the output of the gdalinfo command line utility.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_05", "repo": "django", "question": "What are the valid values for the `cache` parameter in the GeoIP2 constructor and what do they correspond to?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The `cache` parameter in GeoIP2.__init__ accepts an integer from the set (0, 1, 2, 4, 8) which correspond to the GeoIPOptions C API settings: MODE_AUTO, MODE_MMAP_EXT, MODE_MMAP, MODE_FILE, and MODE_MEMORY, respectively. The default value is 0, meaning MODE_AUTO. This parameter controls the cache settings when opening up the GeoIP datasets. The mapping is: 0=MODE_AUTO, 1=MODE_MMAP_EXT, 2=MODE_MMAP, 4=MODE_FILE, 8=MODE_MEMORY.", "rubric": [ "Accepts integers from the set (0, 1, 2, 4, 8)", "0 corresponds to MODE_AUTO (the default)", "1 corresponds to MODE_MMAP_EXT", "2 corresponds to MODE_MMAP", "4 corresponds to MODE_FILE", "8 corresponds to MODE_MEMORY", "These correspond to GeoIPOptions C API settings", "Controls cache settings when opening GeoIP datasets" ], "key_files": [ "django/contrib/gis/geoip2.py" ], "source_doc": "[docstring: django/contrib/gis/geoip2.py] django.contrib.gis.geoip2.GeoIP2\ndjango.contrib.gis.geoip2.GeoIP2.__init__:\n Initialize the GeoIP object. No parameters are required to use default\n settings. Keyword arguments may be passed in to customize the locations\n of the GeoIP datasets.\n\n * path: Base directory to where GeoIP data is located or the full path\n to where the city or country data files (*.mmdb) are located.\n Assumes that both the city and country data sets are located in\n this directory; overrides the GEOIP_PATH setting.\n\n * cache: The cache settings when opening up the GeoIP datasets. May be\n an integer in (0, 1, 2, 4, 8) corresponding to the MODE_AUTO,\n MODE_MMAP_EXT, MODE_MMAP, MODE_FILE, and MODE_MEMORY,\n `GeoIPOptions` C API settings, respectively. Defaults to 0,\n meaning MODE_AUTO.\n\n * country: The name of the GeoIP country data file. Defaults to\n 'GeoLite2-Country.mmdb'; overrides the GEOIP_COUNTRY setting.\n\n * city: The name of the GeoIP city data file. Defaults to\n 'GeoLite2-City.mmdb'; overrides the GEOIP_CITY setting.\n\ndjango.contrib.gis.geoip2.GeoIP2.city:\n Return a dictionary of city information for the given IP address or\n Fully Qualified Domain Name (FQDN). Some information in the dictionary\n may be undefined (None).\n\ndjango.contrib.gis.geoip2.GeoIP2.country_code:\n Return the country code for the given IP Address or FQDN.\n\ndjango.contrib.gis.geoip2.GeoIP2.country_name:\n Return the country name for the given IP Address or FQDN.\n\ndjango.contrib.gis.geoip2.GeoIP2.country:\n Return a dictionary with the country code and name when given an\n IP address or a Fully Qualified Domain Name (FQDN). For example, both\n '24.124.1.80' and 'djangoproject.com' are valid parameters.\n\ndjango.contrib.gis.geoip2.GeoIP2.lon_lat:\n Return a tuple of the (longitude, latitude) for the given query.\n\ndjango.contrib.gis.geoip2.GeoIP2.lat_lon:\n Return a tuple of the (latitude, longitude) for the given query.\n\ndjango.contrib.gis.geoip2.GeoIP2.geos:\n Return a GEOS Point object for the given query.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_07", "repo": "django", "question": "Where in Django's GIS GEOS library is LineString initialization defined, and what ownership semantics apply when passing Point objects?", "category": "where", "sub_type": "feature_location", "gold_answer": "When initializing a Django GIS LineString object, you can pass Point objects as arguments (e.g., `ls = LineString(Point(1, 1), Point(2, 2))`). However, the documentation explicitly states that when Point objects are used, ownership is _not_ transferred to the LineString object. This means the original Point objects remain independent and are not consumed or managed by the LineString. The LineString can also be initialized with lists, tuples, or NumPy arrays of X,Y pairs. Additionally, properties like `.x`, `.y`, and `.z` will return either a list or a numpy array depending on availability, and the `_listarr` method returns a list but will return a numpy array if possible.", "rubric": [ "Identifies that LineString initialization is in the GEOS linestring module (django.contrib.gis.geos.linestring)", "States that when Point objects are passed, ownership is NOT transferred to the LineString object", "Mentions that LineString can also be initialized with lists, tuples, or NumPy arrays of X,Y pairs", "Notes that properties like .x, .y, .z return either a list or a numpy array depending on numpy availability", "Explains that the _listarr helper method returns a list by default but a numpy array if numpy is available" ], "key_files": [ "django/contrib/gis/geos/linestring.py" ], "source_doc": "[docstring: django/contrib/gis/geos/linestring.py] django.contrib.gis.geos.linestring.LineString\ndjango.contrib.gis.geos.linestring.LineString.__init__:\n Initialize on the given sequence: may take lists, tuples, NumPy arrays\n of X,Y pairs, or Point objects. If Point objects are used, ownership is\n _not_ transferred to the LineString object.\n\n Examples:\n ls = LineString((1, 1), (2, 2))\n ls = LineString([(1, 1), (2, 2)])\n ls = LineString(array([(1, 1), (2, 2)]))\n ls = LineString(Point(1, 1), Point(2, 2))\n\ndjango.contrib.gis.geos.linestring.LineString.__iter__:\n Allow iteration over this LineString.\n\ndjango.contrib.gis.geos.linestring.LineString.__len__:\n Return the number of points in this LineString.\n\ndjango.contrib.gis.geos.linestring.LineString.tuple:\n Return a tuple version of the geometry from the coordinate sequence.\n\ndjango.contrib.gis.geos.linestring.LineString._listarr:\n Return a sequence (list) corresponding with the given function.\n Return a numpy array if possible.\n\ndjango.contrib.gis.geos.linestring.LineString.array:\n Return a numpy array for the LineString.\n\ndjango.contrib.gis.geos.linestring.LineString.x:\n Return a list or numpy array of the X variable.\n\ndjango.contrib.gis.geos.linestring.LineString.y:\n Return a list or numpy array of the Y variable.\n\ndjango.contrib.gis.geos.linestring.LineString.z:\n Return a list or numpy array of the Z variable.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_06", "repo": "django", "question": "Why does the GEOSGeometry class exist, and what input formats does its constructor support?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The GEOSGeometry class serves as the base encapsulation for GEOS geometry objects in Django's GIS framework. Its constructor accepts several input formats: WKT strings, HEXEWKB strings (which is specifically noted as a PostGIS-specific canonical form), GeoJSON strings (which require GDAL to be available), and WKB data provided as a memoryview object. The `srid` keyword parameter specifies the Source Reference Identifier (SRID) number for the geometry and defaults to None if not provided. The class is described as one that 'generally' encapsulates a GEOS geometry, suggesting it may serve broader purposes or have edge cases beyond simple GEOS geometry wrapping.", "rubric": [ "Explains that GEOSGeometry encapsulates GEOS geometry objects (serving as the base class for geometry handling in Django's GIS framework)", "Mentions support for WKT strings as input", "Mentions support for HEXEWKB strings (noting it is a PostGIS-specific canonical form)", "Mentions support for GeoJSON strings (noting GDAL is required)", "Mentions support for WKB data via memoryview objects", "Explains the srid keyword parameter specifies the Source Reference Identifier and defaults to None", "Notes the class docstring says it 'generally' encapsulates a GEOS geometry, implying broader or edge-case purposes" ], "key_files": [ "django/contrib/gis/geos/geometry.py" ], "source_doc": "[docstring: django/contrib/gis/geos/geometry.py] django.contrib.gis.geos.geometry.GEOSGeometry\ndjango.contrib.gis.geos.geometry.GEOSGeometry:\n A class that, generally, encapsulates a GEOS geometry.\n\ndjango.contrib.gis.geos.geometry.GEOSGeometry.__init__:\n The base constructor for GEOS geometry objects. It may take the\n following inputs:\n\n * strings:\n - WKT\n - HEXEWKB (a PostGIS-specific canonical form)\n - GeoJSON (requires GDAL)\n * memoryview:\n - WKB\n\n The `srid` keyword specifies the Source Reference Identifier (SRID)\n number for this Geometry. If not provided, it defaults to None.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_09", "repo": "django", "question": "What does the ListOptionAction in ogrinspect do when the input value is 'true' or 'True' instead of a comma-separated list?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The ListOptionAction class in django/contrib/gis/management/commands/ogrinspect.py is a custom argparse action designed specifically for `ogrinspect` keywords that require a string list. However, it has special behavior: if the string value is 'True' or 'true', the option value will be converted to a boolean instead of remaining a string list. This means the action serves a dual purpose - it can produce either a list of strings or a boolean True value depending on the input, which is a non-obvious behavioral detail that would not be apparent from examining the class name or its code structure alone.", "rubric": [ "Explains that ListOptionAction is a custom argparse action for ogrinspect keywords that require a string list", "States that when the value is 'True' or 'true' (case-insensitive check via .lower()), it sets the option to boolean True instead of a list", "Explains that otherwise (non-true values), it splits the value by commas to produce a list of strings", "Notes the dual-purpose nature: the action can produce either a boolean True or a list of strings depending on input" ], "key_files": [ "django/contrib/gis/management/commands/ogrinspect.py" ], "source_doc": "[docstring: django/contrib/gis/management/commands/ogrinspect.py] django.contrib.gis.management.commands.ogrinspect.ListOptionAction\ndjango.contrib.gis.management.commands.ogrinspect.ListOptionAction:\n Custom argparse action for `ogrinspect` keywords that require\n a string list. If the string is 'True'/'true' then the option\n value will be a boolean instead.", "verification_verdict": "warn", "verification_issues": [ "The claim that 'this is a non-obvious behavioral detail that would not be apparent from examining the class name or its code structure alone' is an editorial/subjective statement not supported by the documentation, though it doesn't contradict it.", "The claim about 'dual purpose - it can produce either a list of strings or a boolean True value' is a plausible extrapolation from the documentation which states 'the option value will be a boolean instead', but the documentation doesn't explicitly say 'boolean True value' - it just says 'a boolean'.", "The phrase 'instead of remaining a string list' is a reasonable inference but adds specificity not explicitly stated in the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_08", "repo": "django", "question": "How should `_set_list` be implemented when subclassing `ListMixin`, and what pitfalls must implementors watch out for?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "When implementing the `_set_list` method in a class derived from `ListMixin`, you must handle the fact that the `items` parameter may be a generator which calls `_get_single_internal`. Because of this, you must cache the values into a temporary list (e.g., `temp = list(items)`) before overwriting/clobbering the original storage. If you don't do this, you risk corrupting data because the generator is reading from the same storage you're about to overwrite. Additionally, if `_get_single_internal` and `_get_single_external` return different types of objects, the `_set_list` implementation must distinguish between the two types and handle each appropriately. If `_set_single` is left undefined, all mutations will result in rebuilding the entire object using `_set_list` instead of modifying individual items in place.", "rubric": [ "Must mention that items parameter may be a generator that calls _get_single_internal, so values must be cached into a temporary list before overwriting storage", "Must explain the risk of data corruption if the generator reads from the same storage being overwritten (clobbered)", "Must note that if _get_single_internal and _get_single_external return different types, _set_list must distinguish and handle each type appropriately", "Must explain that if _set_single is left undefined, all mutations will rebuild the entire object via _set_list rather than modifying individual items in place" ], "key_files": [ "django/contrib/gis/geos/mutable_list.py" ], "source_doc": "[docstring: django/contrib/gis/geos/mutable_list.py] django.contrib.gis.geos.mutable_list.ListMixin\ndjango.contrib.gis.geos.mutable_list.ListMixin:\n A base class which provides complete list interface.\n Derived classes must call ListMixin's __init__() function\n and implement the following:\n\n function _get_single_external(self, i):\n Return single item with index i for general use.\n The index i will always satisfy 0 <= i < len(self).\n\n function _get_single_internal(self, i):\n Same as above, but for use within the class [Optional]\n Note that if _get_single_internal and _get_single_internal return\n different types of objects, _set_list must distinguish\n between the two and handle each appropriately.\n\n function _set_list(self, length, items):\n Recreate the entire object.\n\n NOTE: items may be a generator which calls _get_single_internal.\n Therefore, it is necessary to cache the values in a temporary:\n temp = list(items)\n before clobbering the original storage.\n\n function _set_single(self, i, value):\n Set the single item at index i to value [Optional]\n If left undefined, all mutations will result in rebuilding\n the object using _set_list.\n\n function __len__(self):\n Return the length\n\n int _minlength:\n The minimum legal length [Optional]\n\n int _maxlength:\n The maximum legal length [Optional]\n\n type or tuple _allowed:\n A type or tuple of allowed item types [Optional]\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__getitem__:\n Get the item(s) at the specified index/slice.\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__delitem__:\n Delete the item(s) at the specified index/slice.\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__setitem__:\n Set the item(s) at the specified index/slice.\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__add__:\n add another list-like object\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__radd__:\n add to another list-like object\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__iadd__:\n add another list-like object to self\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__mul__:\n multiply\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__rmul__:\n multiply\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.__imul__:\n multiply\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.count:\n Standard list count method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.index:\n Standard list index method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.append:\n Standard list append method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.extend:\n Standard list extend method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.insert:\n Standard list insert method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.pop:\n Standard list pop method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.remove:\n Standard list remove method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.reverse:\n Standard list reverse method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin.sort:\n Standard list sort method\n\ndjango.contrib.gis.geos.mutable_list.ListMixin._set_slice:\n Assign values to a slice of the object\n\ndjango.contrib.gis.geos.mutable_list.ListMixin._assign_extended_slice_rebuild:\n Assign an extended slice by rebuilding entire list\n\ndjango.contrib.gis.geos.mutable_list.ListMixin._assign_extended_slice:\n Assign an extended slice by re-assigning individual items\n\ndjango.contrib.gis.geos.mutable_list.ListMixin._assign_simple_slice:\n Assign a simple slice; Can assign slice of any length", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "django_gen_10", "repo": "django", "question": "Why does Django's MeasureBase class use `unit_attname` and `default_units` methods instead of directly using unit strings as attribute names?", "category": "why", "sub_type": "performance", "gold_answer": "The `unit_attname` method in Django's `MeasureBase` class is designed to translate human-readable unit strings (like 'metre') into their corresponding short attribute names (like 'm'). This design choice allows the measurement system to accept verbose unit names from users while internally using concise attribute identifiers. The method raises an `AttributeError` specifically when it cannot find a matching attribute for the given unit string, providing a clear error signal rather than returning None or a default value. The `default_units` method serves to extract both the unit value and the default units from keyword arguments, enabling a flexible initialization pattern where measurements can be created with various unit specifications while maintaining a canonical internal representation.", "rubric": [ "Explains that unit_attname translates verbose/human-readable unit names (like 'metre') into short attribute names (like 'm')", "Mentions that this allows users to specify units in various ways (verbose names, aliases, case-insensitive) while maintaining concise internal identifiers", "Notes that unit_attname raises AttributeError when no matching unit is found, rather than returning None or a default", "Explains that default_units extracts both the converted value and the canonical unit name from keyword arguments, enabling flexible initialization with different unit specifications", "Describes how this design enables a canonical internal representation (standard unit) while accepting varied user input" ], "key_files": [ "django/contrib/gis/measure.py" ], "source_doc": "[docstring: django/contrib/gis/measure.py] django.contrib.gis.measure.MeasureBase\ndjango.contrib.gis.measure.MeasureBase.default_units:\n Return the unit value and the default units specified\n from the given keyword arguments dictionary.\n\ndjango.contrib.gis.measure.MeasureBase.unit_attname:\n Retrieve the unit attribute name for the given unit string.\n For example, if the given unit string is 'metre', return 'm'.\n Raise an AttributeError if an attribute cannot be found.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_02", "repo": "scikit_learn", "question": "Why does `fetch_olivetti_faces` include a `shuffle` parameter instead of always returning data in its natural order?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The `shuffle` parameter exists in `fetch_olivetti_faces` because, by default, the dataset has images of the same person grouped together. The shuffle option is provided specifically to avoid having images of the same person grouped, which is important for machine learning tasks where you want to avoid bias from ordered data (e.g., when splitting into train/test sets sequentially). The design rationale is explicitly stated: shuffling helps 'avoid having images of the same person grouped,' meaning the natural ordering of the dataset clusters all 10 images of each subject consecutively. Without shuffling, a naive sequential train/test split could result in some subjects appearing only in training and others only in testing, which would not properly evaluate generalization.", "rubric": [ "Explains that the dataset naturally has images of the same person grouped together (10 consecutive images per subject)", "States that shuffling avoids having images of the same person grouped, which matters for machine learning tasks like train/test splitting", "Mentions that without shuffling, sequential splits could result in some subjects only in training and others only in testing, harming generalization evaluation" ], "key_files": [ "sklearn/datasets/_olivetti_faces.py" ], "source_doc": "[docstring: sklearn/datasets/_olivetti_faces.py] sklearn.datasets._olivetti_faces.fetch_olivetti_faces\nLoad the Olivetti faces data-set from AT&T (classification).\n\n Download it if necessary.\n\n ================= =====================\n Classes 40\n Samples total 400\n Dimensionality 4096\n Features real, between 0 and 1\n ================= =====================\n\n Read more in the :ref:`User Guide `.\n\n Parameters\n ----------\n data_home : str or path-like, default=None\n Specify another download and cache folder for the datasets. By default\n all scikit-learn data is stored in '~/scikit_learn_data' subfolders.\n\n shuffle : bool, default=False\n If True the order of the dataset is shuffled to avoid having\n images of the same person grouped.\n\n random_state : int, RandomState instance or None, default=0\n Determines random number generation for dataset shuffling. Pass an int\n for reproducible output across multiple function calls.\n See :term:`Glossary `.\n\n download_if_missing : bool, default=True\n If False, raise an OSError if the data is not locally available\n instead of trying to download the data from the source site.\n\n return_X_y : bool, default=False\n If True, returns `(data, target)` instead of a `Bunch` object. See\n below for more information about the `data` and `target` object.\n\n .. versionadded:: 0.22\n\n n_retries : int, default=3\n Number of retries when HTTP errors are encountered.\n\n .. versionadded:: 1.5\n\n delay : float, default=1.0\n Number of seconds between retries.\n\n .. versionadded:: 1.5\n\n Returns\n -------\n data : :class:`~sklearn.utils.Bunch`\n Dictionary-like object, with the following attributes.\n\n data: ndarray, shape (400, 4096)\n Each row corresponds to a ravelled\n face image of original size 64 x 64 pixels.\n images : ndarray, shape (400, 64, 64)\n Each row is a face image\n corresponding to one of the 40 subjects of the dataset.\n target : ndarray, shape (400,)\n Labels associated to each face image.\n Those labels are ranging from 0-39 and correspond to the\n Subject IDs.\n DESCR : str\n Description of the modified Olivetti Faces Dataset.\n\n (data, target) : tuple if `return_X_y=True`\n Tuple with the `data` and `target` objects described above.\n\n .. versionadded:: 0.22\n\n Examples\n --------\n >>> from sklearn.datasets import fetch_olivetti_faces\n >>> olivetti_faces = fetch_olivetti_faces()\n >>> olivetti_faces.data.shape\n (400, 4096)\n >>> olivetti_faces.target.shape\n (400,)\n >>> olivetti_faces.images.shape\n (400, 64, 64)", "verification_verdict": "warn", "verification_issues": [ "The claim that there are '10 images of each subject' is not explicitly stated in the documentation, though it can be inferred from 400 samples / 40 classes = 10 images per subject. This is a reasonable inference but not directly stated.", "The discussion about train/test split implications is a plausible extrapolation of why shuffling matters, but is not explicitly stated in the documentation.", "The core claim about shuffle's purpose \u2014 'avoid having images of the same person grouped' \u2014 is directly supported by the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_03", "repo": "scikit_learn", "question": "Where do the training samples end up in the returned data when calling fetch_rcv1 with subset='all' and no shuffling?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "When using fetch_rcv1 with subset='all' and shuffle=False, the training samples (23149 samples) come first, followed by the test set (781265 samples). This follows the official LYRL2004 chronological split. The data is stored by default in '~/scikit_learn_data' subfolders. The returned data sparse matrix is in CSR format with 0.16% non-zero values, and the target sparse matrix is also in CSR format with 3.15% non-zero values, where each sample has a value of 1 in its categories and 0 in others.", "rubric": [ "Training samples (23149) come first, followed by the test set (781265 samples)", "This follows the official LYRL2004 chronological split", "Data is stored by default in '~/scikit_learn_data' subfolders (specifically an 'RCV1' subdirectory)", "The data sparse matrix is in CSR format with 0.16% non-zero values", "The target sparse matrix is in CSR format with 3.15% non-zero values", "Each sample in the target has a value of 1 in its categories and 0 in others" ], "key_files": [ "sklearn/datasets/_rcv1.py" ], "source_doc": "[docstring: sklearn/datasets/_rcv1.py] sklearn.datasets._rcv1.fetch_rcv1\nLoad the RCV1 multilabel dataset (classification).\n\n Download it if necessary.\n\n Version: RCV1-v2, vectors, full sets, topics multilabels.\n\n ================= =====================\n Classes 103\n Samples total 804414\n Dimensionality 47236\n Features real, between 0 and 1\n ================= =====================\n\n Read more in the :ref:`User Guide `.\n\n .. versionadded:: 0.17\n\n Parameters\n ----------\n data_home : str or path-like, default=None\n Specify another download and cache folder for the datasets. By default\n all scikit-learn data is stored in '~/scikit_learn_data' subfolders.\n\n subset : {'train', 'test', 'all'}, default='all'\n Select the dataset to load: 'train' for the training set\n (23149 samples), 'test' for the test set (781265 samples),\n 'all' for both, with the training samples first if shuffle is False.\n This follows the official LYRL2004 chronological split.\n\n download_if_missing : bool, default=True\n If False, raise an OSError if the data is not locally available\n instead of trying to download the data from the source site.\n\n random_state : int, RandomState instance or None, default=None\n Determines random number generation for dataset shuffling. Pass an int\n for reproducible output across multiple function calls.\n See :term:`Glossary `.\n\n shuffle : bool, default=False\n Whether to shuffle dataset.\n\n return_X_y : bool, default=False\n If True, returns ``(dataset.data, dataset.target)`` instead of a Bunch\n object. See below for more information about the `dataset.data` and\n `dataset.target` object.\n\n .. versionadded:: 0.20\n\n n_retries : int, default=3\n Number of retries when HTTP errors are encountered.\n\n .. versionadded:: 1.5\n\n delay : float, default=1.0\n Number of seconds between retries.\n\n .. versionadded:: 1.5\n\n Returns\n -------\n dataset : :class:`~sklearn.utils.Bunch`\n Dictionary-like object. Returned only if `return_X_y` is False.\n `dataset` has the following attributes:\n\n - data : sparse matrix of shape (804414, 47236), dtype=np.float64\n The array has 0.16% of non zero values. Will be of CSR format.\n - target : sparse matrix of shape (804414, 103), dtype=np.uint8\n Each sample has a value of 1 in its categories, and 0 in others.\n The array has 3.15% of non zero values. Will be of CSR format.\n - sample_id : ndarray of shape (804414,), dtype=np.uint32,\n Identification number of each sample, as ordered in dataset.data.\n - target_names : ndarray of shape (103,), dtype=object\n Names of each target (RCV1 topics), as ordered in dataset.target.\n - DESCR : str\n Description of the RCV1 dataset.\n\n (data, target) : tuple\n A tuple consisting of `dataset.data` and `dataset.target`, as\n described above. Returned only if `return_X_y` is True.\n\n .. versionadded:: 0.20\n\n Examples\n --------\n >>> from sklearn.datasets import fetch_rcv1\n >>> rcv1 = fetch_rcv1()\n >>> rcv1.data.shape\n (804414, 47236)\n >>> rcv1.target.shape\n (804414, 103)", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_04", "repo": "scikit_learn", "question": "How does make_classification generate its synthetic dataset, and what are its key edge cases around label noise, feature ordering, and scaling?", "category": "how", "sub_type": "system_design", "gold_answer": "The make_classification function generates data through a multi-step process: First, it creates clusters of points that are normally distributed (std=1) around the vertices of an n_informative-dimensional hypercube with sides of length 2*class_sep. An equal number of clusters is assigned to each class. Within each cluster, informative features are drawn independently from N(0, 1) and then randomly linearly combined to add covariance. The clusters are then placed on the hypercube vertices.\n\nWithout shuffling, features are stacked horizontally in a specific order: (1) the primary n_informative features, (2) n_redundant linear combinations of the informative features, (3) n_repeated duplicates drawn randomly with replacement from informative and redundant features, and (4) remaining features filled with random noise. This means all useful features are in columns X[:, :n_informative + n_redundant + n_repeated].\n\nImportant edge cases and behavioral details include:\n- The default flip_y=0.01 means labels have noise by default, which might lead to fewer than n_classes distinct classes appearing in y.\n- If the sum of weights exceeds 1, more than n_samples samples may be returned.\n- The actual class proportions will not exactly match the specified weights when flip_y isn't 0.\n- Scaling happens after shifting when both shift and scale parameters are applied.\n- When shift is None, features are shifted by a random value drawn in [-class_sep, class_sep].\n- When scale is None, features are scaled by a random value drawn in [1, 100].\n\nThe algorithm is adapted from Guyon (2003) and was specifically designed to generate the 'Madelon' dataset used in the NIPS 2003 variable selection benchmark.", "rubric": [ "Explains that clusters are normally distributed (std=1) around vertices of an n_informative-dimensional hypercube with sides of length 2*class_sep", "Describes that informative features are drawn from N(0,1) and randomly linearly combined (multiplied by a random matrix A) to introduce covariance within each cluster", "Explains the feature stacking order without shuffle: informative, then redundant (linear combinations of informative), then repeated (duplicates from informative+redundant), then random noise", "Notes that useful features without shuffling are in columns X[:, :n_informative + n_redundant + n_repeated]", "Mentions that flip_y defaults to 0.01, adding label noise that may result in fewer than n_classes distinct labels in y", "Explains that if sum of weights exceeds 1, more than n_samples samples may be returned", "Notes that scaling happens after shifting when both shift and scale are applied", "Explains that when shift is None, features are shifted by random values in [-class_sep, class_sep], and when scale is None, features are scaled by random values in [1, 100]", "Mentions the algorithm is adapted from Guyon (2003) and was designed to generate the Madelon dataset" ], "key_files": [ "sklearn/datasets/_samples_generator.py" ], "source_doc": "[docstring: sklearn/datasets/_samples_generator.py] sklearn.datasets._samples_generator.make_classification\nGenerate a random n-class classification problem.\n\n This initially creates clusters of points normally distributed (std=1)\n about vertices of an ``n_informative``-dimensional hypercube with sides of\n length ``2*class_sep`` and assigns an equal number of clusters to each\n class. It introduces interdependence between these features and adds\n various types of further noise to the data.\n\n Without shuffling, ``X`` horizontally stacks features in the following\n order: the primary ``n_informative`` features, followed by ``n_redundant``\n linear combinations of the informative features, followed by ``n_repeated``\n duplicates, drawn randomly with replacement from the informative and\n redundant features. The remaining features are filled with random noise.\n Thus, without shuffling, all useful features are contained in the columns\n ``X[:, :n_informative + n_redundant + n_repeated]``.\n\n Read more in the :ref:`User Guide `.\n\n Parameters\n ----------\n n_samples : int, default=100\n The number of samples.\n\n n_features : int, default=20\n The total number of features. These comprise ``n_informative``\n informative features, ``n_redundant`` redundant features,\n ``n_repeated`` duplicated features and\n ``n_features-n_informative-n_redundant-n_repeated`` useless features\n drawn at random.\n\n n_informative : int, default=2\n The number of informative features. Each class is composed of a number\n of gaussian clusters each located around the vertices of a hypercube\n in a subspace of dimension ``n_informative``. For each cluster,\n informative features are drawn independently from N(0, 1) and then\n randomly linearly combined within each cluster in order to add\n covariance. The clusters are then placed on the vertices of the\n hypercube.\n\n n_redundant : int, default=2\n The number of redundant features. These features are generated as\n random linear combinations of the informative features.\n\n n_repeated : int, default=0\n The number of duplicated features, drawn randomly from the informative\n and the redundant features.\n\n n_classes : int, default=2\n The number of classes (or labels) of the classification problem.\n\n n_clusters_per_class : int, default=2\n The number of clusters per class.\n\n weights : array-like of shape (n_classes,) or (n_classes - 1,), default=None\n The proportions of samples assigned to each class. If None, then\n classes are balanced. Note that if ``len(weights) == n_classes - 1``,\n then the last class weight is automatically inferred.\n More than ``n_samples`` samples may be returned if the sum of\n ``weights`` exceeds 1. Note that the actual class proportions will\n not exactly match ``weights`` when ``flip_y`` isn't 0.\n\n flip_y : float, default=0.01\n The fraction of samples whose class is assigned randomly. Larger\n values introduce noise in the labels and make the classification\n task harder. Note that the default setting flip_y > 0 might lead\n to less than ``n_classes`` in y in some cases.\n\n class_sep : float, default=1.0\n The factor multiplying the hypercube size. Larger values spread\n out the clusters/classes and make the classification task easier.\n\n hypercube : bool, default=True\n If True, the clusters are put on the vertices of a hypercube. If\n False, the clusters are put on the vertices of a random polytope.\n\n shift : float, ndarray of shape (n_features,) or None, default=0.0\n Shift features by the specified value. If None, then features\n are shifted by a random value drawn in [-class_sep, class_sep].\n\n scale : float, ndarray of shape (n_features,) or None, default=1.0\n Multiply features by the specified value. If None, then features\n are scaled by a random value drawn in [1, 100]. Note that scaling\n happens after shifting.\n\n shuffle : bool, default=True\n Shuffle the samples and the features.\n\n random_state : int, RandomState instance or None, default=None\n Determines random number generation for dataset creation. Pass an int\n for reproducible output across multiple function calls.\n See :term:`Glossary `.\n\n return_X_y : bool, default=True\n If True, a tuple ``(X, y)`` instead of a Bunch object is returned.\n\n .. versionadded:: 1.7\n\n Returns\n -------\n data : :class:`~sklearn.utils.Bunch` if `return_X_y` is `False`.\n Dictionary-like object, with the following attributes.\n\n DESCR : str\n A description of the function that generated the dataset.\n parameter : dict\n A dictionary that stores the values of the arguments passed to the\n generator function.\n feature_info : list of len(n_features)\n A description for each generated feature.\n X : ndarray of shape (n_samples, n_features)\n The generated samples.\n y : ndarray of shape (n_samples,)\n An integer label for class membership of each sample.\n\n .. versionadded:: 1.7\n\n (X, y) : tuple if ``return_X_y`` is True\n A tuple of generated samples and labels.\n\n See Also\n --------\n make_blobs : Simplified variant.\n make_multilabel_classification : Unrelated generator for multilabel tasks.\n\n Notes\n -----\n The algorithm is adapted from Guyon [1] and was designed to generate\n the \"Madelon\" dataset.\n\n References\n ----------\n .. [1] I. Guyon, \"Design of experiments for the NIPS 2003 variable\n selection benchmark\", 2003.\n\n Examples\n --------\n >>> from sklearn.datasets import make_classification\n >>> X, y = make_classification(random_state=42)\n >>> X.shape\n (100, 20)\n >>> y.shape\n (100,)\n >>> list(y[:5])\n [np.int64(0), np.int64(0), np.int64(1), np.int64(1), np.int64(0)]", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_01", "repo": "scikit_learn", "question": "What are the key characteristics and design choices of the LFW pairs dataset loader, including its subset options, target encoding, and image slicing rationale?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "In the LFW pairs dataset, the 'pairs' version corresponds to the 'restricted task' from the original paper, where the experimenter should not use the name of a person to infer the equivalence or non-equivalence of two face images that are not explicitly given in the training set. The dataset has 2 classes, 13233 total samples, dimensionality of 5828, and features are real values between 0 and 255. The original images are 250 x 250 pixels, but the default slice and resize arguments reduce them to 62 x 47. The slice_ parameter exists specifically to extract the 'interesting' part of the jpeg files and avoid using statistical correlation from the background. The target_names array maps 0 to 'Different persons' and 1 to 'Same person'. The '10_folds' subset option is the official evaluation set meant to be used with 10-folds cross validation.", "rubric": [ "The 'pairs' version corresponds to the 'restricted task' where the experimenter should not use person names to infer equivalence/non-equivalence of face images not in the training set", "The dataset has 2 classes, 13233 total samples, dimensionality of 5828, with real features between 0 and 255", "Original images are 250x250 pixels, but default slice and resize arguments reduce them to 62x47", "The slice_ parameter extracts the 'interesting' part of jpeg files to avoid statistical correlation from the background", "target_names maps 0 to 'Different persons' and 1 to 'Same person'", "The '10_folds' subset is the official evaluation set meant to be used with 10-folds cross validation" ], "key_files": [ "sklearn/datasets/_lfw.py" ], "source_doc": "[docstring: sklearn/datasets/_lfw.py] sklearn.datasets._lfw.fetch_lfw_pairs\nLoad the Labeled Faces in the Wild (LFW) pairs dataset (classification).\n\n Download it if necessary.\n\n ================= =======================\n Classes 2\n Samples total 13233\n Dimensionality 5828\n Features real, between 0 and 255\n ================= =======================\n\n In the `original paper `_\n the \"pairs\" version corresponds to the \"restricted task\", where\n the experimenter should not use the name of a person to infer\n the equivalence or non-equivalence of two face images that\n are not explicitly given in the training set.\n\n The original images are 250 x 250 pixels, but the default slice and resize\n arguments reduce them to 62 x 47.\n\n Read more in the :ref:`User Guide `.\n\n Parameters\n ----------\n subset : {'train', 'test', '10_folds'}, default='train'\n Select the dataset to load: 'train' for the development training\n set, 'test' for the development test set, and '10_folds' for the\n official evaluation set that is meant to be used with a 10-folds\n cross validation.\n\n data_home : str or path-like, default=None\n Specify another download and cache folder for the datasets. By\n default all scikit-learn data is stored in '~/scikit_learn_data'\n subfolders.\n\n funneled : bool, default=True\n Download and use the funneled variant of the dataset.\n\n resize : float, default=0.5\n Ratio used to resize the each face picture.\n\n color : bool, default=False\n Keep the 3 RGB channels instead of averaging them to a single\n gray level channel. If color is True the shape of the data has\n one more dimension than the shape with color = False.\n\n slice_ : tuple of slice, default=(slice(70, 195), slice(78, 172))\n Provide a custom 2D slice (height, width) to extract the\n 'interesting' part of the jpeg files and avoid use statistical\n correlation from the background.\n\n download_if_missing : bool, default=True\n If False, raise an OSError if the data is not locally available\n instead of trying to download the data from the source site.\n\n n_retries : int, default=3\n Number of retries when HTTP errors are encountered.\n\n .. versionadded:: 1.5\n\n delay : float, default=1.0\n Number of seconds between retries.\n\n .. versionadded:: 1.5\n\n Returns\n -------\n data : :class:`~sklearn.utils.Bunch`\n Dictionary-like object, with the following attributes.\n\n data : ndarray of shape (2200, 5828). Shape depends on ``subset``.\n Each row corresponds to 2 ravel'd face images\n of original size 62 x 47 pixels.\n Changing the ``slice_``, ``resize`` or ``subset`` parameters\n will change the shape of the output.\n pairs : ndarray of shape (2200, 2, 62, 47). Shape depends on ``subset``\n Each row has 2 face images corresponding\n to same or different person from the dataset\n containing 5749 people. Changing the ``slice_``,\n ``resize`` or ``subset`` parameters will change the shape of the\n output.\n target : numpy array of shape (2200,). Shape depends on ``subset``.\n Labels associated to each pair of images.\n The two label values being different persons or the same person.\n target_names : numpy array of shape (2,)\n Explains the target values of the target array.\n 0 corresponds to \"Different person\", 1 corresponds to \"same person\".\n DESCR : str\n Description of the Labeled Faces in the Wild (LFW) dataset.\n\n Examples\n --------\n >>> from sklearn.datasets import fetch_lfw_pairs\n >>> lfw_pairs_train = fetch_lfw_pairs(subset='train')\n >>> list(lfw_pairs_train.target_names)\n [np.str_('Different persons'), np.str_('Same person')]\n >>> lfw_pairs_train.pairs.shape\n (2200, 2, 62, 47)\n >>> lfw_pairs_train.data.shape\n (2200, 5828)\n >>> lfw_pairs_train.target.shape\n (2200,)", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_05", "repo": "scikit_learn", "question": "What is the generative process used by make_multilabel_classification, and what role does rejection sampling play in it?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The generative process for make_multilabel_classification works as follows: For each sample, (1) the number of labels n is picked from a Poisson distribution with expected value n_labels, (2) n times a class c is chosen from a Multinomial distribution parameterized by theta, (3) the document length k is picked from a Poisson distribution with expected value 'length', and (4) k times a word w is chosen from a Multinomial distribution parameterized by theta_c (the class-conditional word distribution). Rejection sampling is employed to ensure that n is never zero or more than n_classes, that the document length is never zero, and that already-chosen classes are rejected (no duplicate class selections for a single sample). The 'length' parameter specifically represents the sum of the features (described as 'number of words if documents'), not the dimensionality of the feature vector.", "rubric": [ "The number of labels n per sample is drawn from a Poisson distribution with expected value n_labels", "n times, a class c is chosen from a Multinomial distribution parameterized by theta (the prior class probability p_c)", "The document length k is drawn from a Poisson distribution with expected value equal to the length parameter", "k times, a word w is chosen from a Multinomial distribution parameterized by the class-conditional word distribution (theta_c / p_w_c)", "Rejection sampling ensures n (number of labels) is never zero (when allow_unlabeled is False) or more than n_classes", "Rejection sampling ensures the document length is never zero", "Already-chosen classes are rejected so no duplicate class is selected for a single sample", "The length parameter represents the sum of features (number of words), not the dimensionality of the feature vector" ], "key_files": [ "sklearn/datasets/_samples_generator.py" ], "source_doc": "[docstring: sklearn/datasets/_samples_generator.py] sklearn.datasets._samples_generator.make_multilabel_classification\nGenerate a random multilabel classification problem.\n\n For each sample, the generative process is:\n - pick the number of labels: n ~ Poisson(n_labels)\n - n times, choose a class c: c ~ Multinomial(theta)\n - pick the document length: k ~ Poisson(length)\n - k times, choose a word: w ~ Multinomial(theta_c)\n\n In the above process, rejection sampling is used to make sure that\n n is never zero or more than `n_classes`, and that the document length\n is never zero. Likewise, we reject classes which have already been chosen.\n\n For an example of usage, see\n :ref:`sphx_glr_auto_examples_datasets_plot_random_multilabel_dataset.py`.\n\n Read more in the :ref:`User Guide `.\n\n Parameters\n ----------\n n_samples : int, default=100\n The number of samples.\n\n n_features : int, default=20\n The total number of features.\n\n n_classes : int, default=5\n The number of classes of the classification problem.\n\n n_labels : int, default=2\n The average number of labels per instance. More precisely, the number\n of labels per sample is drawn from a Poisson distribution with\n ``n_labels`` as its expected value, but samples are bounded (using\n rejection sampling) by ``n_classes``, and must be nonzero if\n ``allow_unlabeled`` is False.\n\n length : int, default=50\n The sum of the features (number of words if documents) is drawn from\n a Poisson distribution with this expected value.\n\n allow_unlabeled : bool, default=True\n If ``True``, some instances might not belong to any class.\n\n sparse : bool, default=False\n If ``True``, return a sparse feature matrix.\n\n .. versionadded:: 0.17\n parameter to allow *sparse* output.\n\n return_indicator : {'dense', 'sparse'} or False, default='dense'\n If ``'dense'`` return ``Y`` in the dense binary indicator format. If\n ``'sparse'`` return ``Y`` in the sparse binary indicator format.\n ``False`` returns a list of lists of labels.\n\n return_distributions : bool, default=False\n If ``True``, return the prior class probability and conditional\n probabilities of features given classes, from which the data was\n drawn.\n\n random_state : int, RandomState instance or None, default=None\n Determines random number generation for dataset creation. Pass an int\n for reproducible output across multiple function calls.\n See :term:`Glossary `.\n\n Returns\n -------\n X : ndarray of shape (n_samples, n_features)\n The generated samples.\n\n Y : {ndarray, sparse matrix} of shape (n_samples, n_classes)\n The label sets. Sparse matrix should be of CSR format.\n\n p_c : ndarray of shape (n_classes,)\n The probability of each class being drawn. Only returned if\n ``return_distributions=True``.\n\n p_w_c : ndarray of shape (n_features, n_classes)\n The probability of each feature being drawn given each class.\n Only returned if ``return_distributions=True``.\n\n Examples\n --------\n >>> from sklearn.datasets import make_multilabel_classification\n >>> X, y = make_multilabel_classification(n_labels=3, random_state=42)\n >>> X.shape\n (100, 20)\n >>> y.shape\n (100, 5)\n >>> list(y[:3])\n [array([1, 1, 0, 1, 0]), array([0, 1, 1, 1, 0]), array([0, 1, 0, 0, 0])]", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_06", "repo": "scikit_learn", "question": "Why does the species distribution dataset loader exist, and what species and data structure does it provide for modeling?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The species distribution dataset from Phillips et al. (2006) represents the geographic distribution of two specific species: Bradypus variegatus (the Brown-throated Sloth) and Microryzomys minutus (the Forest Small Rice Rat, a rodent that lives in Peru, Colombia, Ecuador, Peru, and Venezuela). The dataset serves as a basis for maximum entropy modeling of species geographic distributions. The coverages array contains 14 features measured at each point of a map grid with shape [14, 1592, 1212], where missing data is represented by the special value -9999. The dataset was designed to support ecological modeling research, specifically the approach described in the referenced paper 'Maximum entropy modeling of species geographic distributions' by Phillips, Anderson, and Schapire (Ecological Modelling, 190:231-259, 2006). The purpose of this dataset loader is to provide researchers with geographic species occurrence data split into training (1624 points) and test (620 points) sets, along with environmental coverage features on a regular grid, enabling species distribution modeling experiments.", "rubric": [ "Identifies the two species: Bradypus variegatus (Brown-throated Sloth) and Microryzomys minutus (Forest Small Rice Rat)", "Explains the dataset supports maximum entropy modeling of species geographic distributions (Phillips et al. 2006)", "Describes the coverages array with shape [14, 1592, 1212] containing 14 environmental features with -9999 representing missing data", "Mentions the dataset provides training (1624 points) and test (620 points) splits with species name, longitude, and latitude fields", "States the purpose is to enable species distribution modeling experiments using geographic occurrence data and environmental coverage features" ], "key_files": [ "sklearn/datasets/_species_distributions.py" ], "source_doc": "[docstring: sklearn/datasets/_species_distributions.py] sklearn.datasets._species_distributions.fetch_species_distributions\nLoader for species distribution dataset from Phillips et. al. (2006).\n\n Read more in the :ref:`User Guide `.\n\n Parameters\n ----------\n data_home : str or path-like, default=None\n Specify another download and cache folder for the datasets. By default\n all scikit-learn data is stored in '~/scikit_learn_data' subfolders.\n\n download_if_missing : bool, default=True\n If False, raise an OSError if the data is not locally available\n instead of trying to download the data from the source site.\n\n n_retries : int, default=3\n Number of retries when HTTP errors are encountered.\n\n .. versionadded:: 1.5\n\n delay : float, default=1.0\n Number of seconds between retries.\n\n .. versionadded:: 1.5\n\n Returns\n -------\n data : :class:`~sklearn.utils.Bunch`\n Dictionary-like object, with the following attributes.\n\n coverages : array, shape = [14, 1592, 1212]\n These represent the 14 features measured\n at each point of the map grid.\n The latitude/longitude values for the grid are discussed below.\n Missing data is represented by the value -9999.\n train : record array, shape = (1624,)\n The training points for the data. Each point has three fields:\n\n - train['species'] is the species name\n - train['dd long'] is the longitude, in degrees\n - train['dd lat'] is the latitude, in degrees\n test : record array, shape = (620,)\n The test points for the data. Same format as the training data.\n Nx, Ny : integers\n The number of longitudes (x) and latitudes (y) in the grid\n x_left_lower_corner, y_left_lower_corner : floats\n The (x,y) position of the lower-left corner, in degrees\n grid_size : float\n The spacing between points of the grid, in degrees\n\n Notes\n -----\n\n This dataset represents the geographic distribution of species.\n The dataset is provided by Phillips et. al. (2006).\n\n The two species are:\n\n - `\"Bradypus variegatus\"\n `_ ,\n the Brown-throated Sloth.\n\n - `\"Microryzomys minutus\"\n `_ ,\n also known as the Forest Small Rice Rat, a rodent that lives in Peru,\n Colombia, Ecuador, Peru, and Venezuela.\n\n References\n ----------\n\n * `\"Maximum entropy modeling of species geographic distributions\"\n `_\n S. J. Phillips, R. P. Anderson, R. E. Schapire - Ecological Modelling,\n 190:231-259, 2006.\n\n Examples\n --------\n >>> from sklearn.datasets import fetch_species_distributions\n >>> species = fetch_species_distributions()\n >>> species.train[:5]\n array([(b'microryzomys_minutus', -64.7 , -17.85 ),\n (b'microryzomys_minutus', -67.8333, -16.3333),\n (b'microryzomys_minutus', -67.8833, -16.3 ),\n (b'microryzomys_minutus', -67.8 , -16.2667),\n (b'microryzomys_minutus', -67.9833, -15.9 )],\n dtype=[('species', 'S22'), ('dd long', '>> from sklearn.datasets import dump_svmlight_file, make_classification\n >>> X, y = make_classification(random_state=0)\n >>> output_file = \"my_dataset.svmlight\"\n >>> dump_svmlight_file(X, y, output_file) # doctest: +SKIP", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_08", "repo": "scikit_learn", "question": "How does the `remove` parameter in `fetch_20newsgroups` filter post content, and what are the reliability differences between its options?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "The `remove` parameter in `fetch_20newsgroups` accepts a tuple that may contain any subset of ('headers', 'footers', 'quotes'). These filters work differently in terms of reliability: 'headers' follows an exact standard and is therefore reliably detected and removed. However, the 'footers' filter (which removes blocks at the ends of posts that look like signatures) and the 'quotes' filter (which removes lines that appear to be quoting another post) are not always correct \u2014 meaning they may sometimes fail to detect or incorrectly detect such content. The purpose of removing these elements is to prevent classifiers from overfitting on metadata rather than learning from the actual content of the newsgroup posts.", "rubric": [ "Accepts a tuple containing any subset of ('headers', 'footers', 'quotes')", "'headers' removes everything before the first blank line (follows an exact standard and is reliably detected)", "'footers' removes signature blocks at the ends of posts using a heuristic (not always correct)", "'quotes' removes lines matching quote patterns like '>' or '|' or containing 'writes:' (not always correct)", "The purpose is to prevent classifiers from overfitting on metadata rather than learning from actual post content" ], "key_files": [ "sklearn/datasets/_twenty_newsgroups.py" ], "source_doc": "[docstring: sklearn/datasets/_twenty_newsgroups.py] sklearn.datasets._twenty_newsgroups.fetch_20newsgroups\nLoad the filenames and data from the 20 newsgroups dataset (classification).\n\n Download it if necessary.\n\n ================= ==========\n Classes 20\n Samples total 18846\n Dimensionality 1\n Features text\n ================= ==========\n\n Read more in the :ref:`User Guide <20newsgroups_dataset>`.\n\n Parameters\n ----------\n data_home : str or path-like, default=None\n Specify a download and cache folder for the datasets. If None,\n all scikit-learn data is stored in '~/scikit_learn_data' subfolders.\n\n subset : {'train', 'test', 'all'}, default='train'\n Select the dataset to load: 'train' for the training set, 'test'\n for the test set, 'all' for both, with shuffled ordering.\n\n categories : array-like, dtype=str, default=None\n If None (default), load all the categories.\n If not None, list of category names to load (other categories\n ignored).\n\n shuffle : bool, default=True\n Whether or not to shuffle the data: might be important for models that\n make the assumption that the samples are independent and identically\n distributed (i.i.d.), such as stochastic gradient descent.\n\n random_state : int, RandomState instance or None, default=42\n Determines random number generation for dataset shuffling. Pass an int\n for reproducible output across multiple function calls.\n See :term:`Glossary `.\n\n remove : tuple, default=()\n May contain any subset of ('headers', 'footers', 'quotes'). Each of\n these are kinds of text that will be detected and removed from the\n newsgroup posts, preventing classifiers from overfitting on\n metadata.\n\n 'headers' removes newsgroup headers, 'footers' removes blocks at the\n ends of posts that look like signatures, and 'quotes' removes lines\n that appear to be quoting another post.\n\n 'headers' follows an exact standard; the other filters are not always\n correct.\n\n download_if_missing : bool, default=True\n If False, raise an OSError if the data is not locally available\n instead of trying to download the data from the source site.\n\n return_X_y : bool, default=False\n If True, returns `(data.data, data.target)` instead of a Bunch\n object.\n\n .. versionadded:: 0.22\n\n n_retries : int, default=3\n Number of retries when HTTP errors are encountered.\n\n .. versionadded:: 1.5\n\n delay : float, default=1.0\n Number of seconds between retries.\n\n .. versionadded:: 1.5\n\n Returns\n -------\n bunch : :class:`~sklearn.utils.Bunch`\n Dictionary-like object, with the following attributes.\n\n data : list of shape (n_samples,)\n The data list to learn.\n target: ndarray of shape (n_samples,)\n The target labels.\n filenames: list of shape (n_samples,)\n The path to the location of the data.\n DESCR: str\n The full description of the dataset.\n target_names: list of shape (n_classes,)\n The names of target classes.\n\n (data, target) : tuple if `return_X_y=True`\n A tuple of two ndarrays. The first contains a 2D array of shape\n (n_samples, n_classes) with each row representing one sample and each\n column representing the features. The second array of shape\n (n_samples,) contains the target samples.\n\n .. versionadded:: 0.22\n\n Examples\n --------\n >>> from sklearn.datasets import fetch_20newsgroups\n >>> cats = ['alt.atheism', 'sci.space']\n >>> newsgroups_train = fetch_20newsgroups(subset='train', categories=cats)\n >>> list(newsgroups_train.target_names)\n ['alt.atheism', 'sci.space']\n >>> newsgroups_train.filenames.shape\n (1073,)\n >>> newsgroups_train.target.shape\n (1073,)\n >>> newsgroups_train.target[:10]\n array([0, 1, 1, 1, 0, 1, 1, 0, 0, 0])", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_09", "repo": "scikit_learn", "question": "What vectorization dependencies and dataset characteristics does `fetch_20newsgroups_vectorized` rely on, and what alternatives are suggested for advanced usage?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The `fetch_20newsgroups_vectorized` function depends on `sklearn.feature_extraction.text.CountVectorizer` with its default settings to perform the vectorization transformation. The resulting counts are then normalized using `sklearn.preprocessing.normalize` (unless normalize=False). For more advanced usage such as stopword filtering or n-gram extraction, users should combine `fetch_20newsgroups` with a custom `CountVectorizer`, `HashingVectorizer`, `TfidfTransformer`, or `TfidfVectorizer`. The dataset has a dimensionality of 130107 features across 18846 total samples divided into 20 classes.", "rubric": [ "Identifies CountVectorizer (with default settings) as the primary vectorization tool used", "Mentions sklearn.preprocessing.normalize is used to normalize the resulting counts (unless normalize=False)", "Lists alternatives for advanced usage: CountVectorizer, HashingVectorizer, TfidfTransformer, or TfidfVectorizer with fetch_20newsgroups", "States the dataset dimensionality is 130107 features", "States the total sample count is 18846 across 20 classes" ], "key_files": [ "sklearn/datasets/_twenty_newsgroups.py" ], "source_doc": "[docstring: sklearn/datasets/_twenty_newsgroups.py] sklearn.datasets._twenty_newsgroups.fetch_20newsgroups_vectorized\nLoad and vectorize the 20 newsgroups dataset (classification).\n\n Download it if necessary.\n\n This is a convenience function; the transformation is done using the\n default settings for\n :class:`~sklearn.feature_extraction.text.CountVectorizer`. For more\n advanced usage (stopword filtering, n-gram extraction, etc.), combine\n fetch_20newsgroups with a custom\n :class:`~sklearn.feature_extraction.text.CountVectorizer`,\n :class:`~sklearn.feature_extraction.text.HashingVectorizer`,\n :class:`~sklearn.feature_extraction.text.TfidfTransformer` or\n :class:`~sklearn.feature_extraction.text.TfidfVectorizer`.\n\n The resulting counts are normalized using\n :func:`sklearn.preprocessing.normalize` unless normalize is set to False.\n\n ================= ==========\n Classes 20\n Samples total 18846\n Dimensionality 130107\n Features real\n ================= ==========\n\n Read more in the :ref:`User Guide <20newsgroups_dataset>`.\n\n Parameters\n ----------\n subset : {'train', 'test', 'all'}, default='train'\n Select the dataset to load: 'train' for the training set, 'test'\n for the test set, 'all' for both, with shuffled ordering.\n\n remove : tuple, default=()\n May contain any subset of ('headers', 'footers', 'quotes'). Each of\n these are kinds of text that will be detected and removed from the\n newsgroup posts, preventing classifiers from overfitting on\n metadata.\n\n 'headers' removes newsgroup headers, 'footers' removes blocks at the\n ends of posts that look like signatures, and 'quotes' removes lines\n that appear to be quoting another post.\n\n data_home : str or path-like, default=None\n Specify a download and cache folder for the datasets. If None,\n all scikit-learn data is stored in '~/scikit_learn_data' subfolders.\n\n download_if_missing : bool, default=True\n If False, raise an OSError if the data is not locally available\n instead of trying to download the data from the source site.\n\n return_X_y : bool, default=False\n If True, returns ``(data.data, data.target)`` instead of a Bunch\n object.\n\n .. versionadded:: 0.20\n\n normalize : bool, default=True\n If True, normalizes each document's feature vector to unit norm using\n :func:`sklearn.preprocessing.normalize`.\n\n .. versionadded:: 0.22\n\n as_frame : bool, default=False\n If True, the data is a pandas DataFrame including columns with\n appropriate dtypes (numeric, string, or categorical). The target is\n a pandas DataFrame or Series depending on the number of\n `target_columns`.\n\n .. versionadded:: 0.24\n\n n_retries : int, default=3\n Number of retries when HTTP errors are encountered.\n\n .. versionadded:: 1.5\n\n delay : float, default=1.0\n Number of seconds between retries.\n\n .. versionadded:: 1.5\n\n Returns\n -------\n bunch : :class:`~sklearn.utils.Bunch`\n Dictionary-like object, with the following attributes.\n\n data: {sparse matrix, dataframe} of shape (n_samples, n_features)\n The input data matrix. If ``as_frame`` is `True`, ``data`` is\n a pandas DataFrame with sparse columns.\n target: {ndarray, series} of shape (n_samples,)\n The target labels. If ``as_frame`` is `True`, ``target`` is a\n pandas Series.\n target_names: list of shape (n_classes,)\n The names of target classes.\n DESCR: str\n The full description of the dataset.\n frame: dataframe of shape (n_samples, n_features + 1)\n Only present when `as_frame=True`. Pandas DataFrame with ``data``\n and ``target``.\n\n .. versionadded:: 0.24\n\n (data, target) : tuple if ``return_X_y`` is True\n `data` and `target` would be of the format defined in the `Bunch`\n description above.\n\n .. versionadded:: 0.20\n\n Examples\n --------\n >>> from sklearn.datasets import fetch_20newsgroups_vectorized\n >>> newsgroups_vectorized = fetch_20newsgroups_vectorized(subset='test')\n >>> newsgroups_vectorized.data.shape\n (7532, 130107)\n >>> newsgroups_vectorized.target.shape\n (7532,)", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "scikit_learn_gen_10", "repo": "scikit_learn", "question": "Why is 'lasso_lars' preferred over 'lasso_cd' as the default algorithm in sparse_encode?", "category": "why", "sub_type": "performance", "gold_answer": "According to the documentation, when choosing between 'lasso_lars' and 'lasso_cd' algorithms in sparse_encode, the 'lasso_lars' algorithm will be faster if the estimated components are sparse. This is a performance-related design guidance provided in the documentation to help users select the appropriate algorithm based on the expected sparsity of their solution. If the components are expected to be sparse, 'lasso_lars' is the recommended choice for better performance, whereas 'lasso_cd' uses coordinate descent and may be preferable when the solution is less sparse.", "rubric": [ "Must mention that lasso_lars is faster when estimated components are sparse", "Should note that lasso_cd uses coordinate descent as an alternative approach", "Should indicate this is a performance-related design choice based on expected sparsity of the solution" ], "key_files": [ "sklearn/decomposition/_dict_learning.py" ], "source_doc": "[docstring: sklearn/decomposition/_dict_learning.py] sklearn.decomposition._dict_learning.sparse_encode\nSparse coding.\n\n Each row of the result is the solution to a sparse coding problem.\n The goal is to find a sparse array `code` such that::\n\n X ~= code * dictionary\n\n Read more in the :ref:`User Guide `.\n\n Parameters\n ----------\n X : array-like of shape (n_samples, n_features)\n Data matrix.\n\n dictionary : array-like of shape (n_components, n_features)\n The dictionary matrix against which to solve the sparse coding of\n the data. Some of the algorithms assume normalized rows for meaningful\n output.\n\n gram : array-like of shape (n_components, n_components), default=None\n Precomputed Gram matrix, `dictionary * dictionary'`.\n\n cov : array-like of shape (n_components, n_samples), default=None\n Precomputed covariance, `dictionary' * X`.\n\n algorithm : {'lasso_lars', 'lasso_cd', 'lars', 'omp', 'threshold'}, default='lasso_lars'\n The algorithm used:\n\n * `'lars'`: uses the least angle regression method\n (`linear_model.lars_path`);\n * `'lasso_lars'`: uses Lars to compute the Lasso solution;\n * `'lasso_cd'`: uses the coordinate descent method to compute the\n Lasso solution (`linear_model.Lasso`). lasso_lars will be faster if\n the estimated components are sparse;\n * `'omp'`: uses orthogonal matching pursuit to estimate the sparse\n solution;\n * `'threshold'`: squashes to zero all coefficients less than\n regularization from the projection `dictionary * data'`.\n\n n_nonzero_coefs : int, default=None\n Number of nonzero coefficients to target in each column of the\n solution. This is only used by `algorithm='lars'` and `algorithm='omp'`\n and is overridden by `alpha` in the `omp` case. If `None`, then\n `n_nonzero_coefs=int(n_features / 10)`.\n\n alpha : float, default=None\n If `algorithm='lasso_lars'` or `algorithm='lasso_cd'`, `alpha` is the\n penalty applied to the L1 norm.\n If `algorithm='threshold'`, `alpha` is the absolute value of the\n threshold below which coefficients will be squashed to zero.\n If `algorithm='omp'`, `alpha` is the tolerance parameter: the value of\n the reconstruction error targeted. In this case, it overrides\n `n_nonzero_coefs`.\n If `None`, default to 1.\n\n copy_cov : bool, default=True\n Whether to copy the precomputed covariance matrix; if `False`, it may\n be overwritten.\n\n init : ndarray of shape (n_samples, n_components), default=None\n Initialization value of the sparse codes. Only used if\n `algorithm='lasso_cd'`.\n\n max_iter : int, default=1000\n Maximum number of iterations to perform if `algorithm='lasso_cd'` or\n `'lasso_lars'`.\n\n n_jobs : int, default=None\n Number of parallel jobs to run.\n ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context.\n ``-1`` means using all processors. See :term:`Glossary `\n for more details.\n\n check_input : bool, default=True\n If `False`, the input arrays X and dictionary will not be checked.\n\n verbose : int, default=0\n Controls the verbosity; the higher, the more messages.\n\n positive : bool, default=False\n Whether to enforce positivity when finding the encoding.\n\n .. versionadded:: 0.20\n\n Returns\n -------\n code : ndarray of shape (n_samples, n_components)\n The sparse codes.\n\n See Also\n --------\n sklearn.linear_model.lars_path : Compute Least Angle Regression or Lasso\n path using LARS algorithm.\n sklearn.linear_model.orthogonal_mp : Solves Orthogonal Matching Pursuit problems.\n sklearn.linear_model.Lasso : Train Linear Model with L1 prior as regularizer.\n SparseCoder : Find a sparse representation of data from a fixed precomputed\n dictionary.\n\n Examples\n --------\n >>> import numpy as np\n >>> from sklearn.decomposition import sparse_encode\n >>> X = np.array([[-1, -1, -1], [0, 0, 3]])\n >>> dictionary = np.array(\n ... [[0, 1, 0],\n ... [-1, -1, 2],\n ... [1, 1, 1],\n ... [0, 1, 1],\n ... [0, 2, 1]],\n ... dtype=np.float64\n ... )\n >>> sparse_encode(X, dictionary, alpha=1e-10)\n array([[ 0., 0., -1., 0., 0.],\n [ 0., 1., 1., 0., 0.]])", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_01", "repo": "matplotlib", "question": "What does `pts_to_prestep` in cbook do, and is there a discrepancy between its description and documented return size?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The `pts_to_prestep` function in matplotlib's cbook module converts N continuous points into a step function representation. There is a notable discrepancy in its documentation: the description states it converts N points to '2N - 1' points, but the Returns section states the output arrays will be length '2N + 1'. The function creates a step function that changes values at the beginning of the intervals (pre-step behavior). For the edge case of N=0 (empty input), the output length will be 0. The function accepts an x array and one or more y arrays (y1, ..., yp), all of which must be the same length as x, and returns them all converted to step format in the same order as input, which can be unpacked as x_out, y1_out, ..., yp_out.", "rubric": [ "Explains that pts_to_prestep converts N continuous points into a step function representation (pre-step behavior, changing values at the beginning of intervals)", "Identifies the discrepancy: the description says '2N - 1' points but the Returns section says '2N + 1' output length", "Notes that the actual implementation uses `max(2 * len(x) - 1, 0)`, confirming the output is 2N-1 (not 2N+1)", "Mentions the function accepts x and one or more y arrays (all same length as x) and returns them converted to step format", "Mentions the edge case: for N=0 (empty input), the output length is 0" ], "key_files": [ "lib/matplotlib/cbook.py" ], "source_doc": "[docstring: lib/matplotlib/cbook.py] lib.matplotlib.cbook.pts_to_prestep\nConvert continuous line to pre-steps.\n\n Given a set of ``N`` points, convert to ``2N - 1`` points, which when\n connected linearly give a step function which changes values at the\n beginning of the intervals.\n\n Parameters\n ----------\n x : array\n The x location of the steps. May be empty.\n\n y1, ..., yp : array\n y arrays to be turned into steps; all must be the same length as ``x``.\n\n Returns\n -------\n array\n The x and y values converted to steps in the same order as the input;\n can be unpacked as ``x_out, y1_out, ..., yp_out``. If the input is\n length ``N``, each of these arrays will be length ``2N + 1``. For\n ``N=0``, the length will be 0.\n\n Examples\n --------\n >>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_02", "repo": "matplotlib", "question": "Why does pts_to_poststep exist as a separate function from pts_to_prestep, and how does its design handle multiple y arrays and empty inputs?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The pts_to_poststep function converts N continuous points to 2N+1 points that, when connected linearly, form a step function which changes values at the END of the intervals (as opposed to pts_to_prestep which changes at the beginning). This design choice distinguishes it from pre-step conversion by defining where the value transition occurs relative to the interval. The function handles the edge case where N=0 by returning arrays of length 0 (rather than length 1 as the 2N+1 formula would suggest). The function accepts multiple y arrays simultaneously (y1, ..., yp) which must all share the same length as x, and returns them all converted in a single call, allowing unpacking like `x_out, y1_out, ..., yp_out`.", "rubric": [ "Explains that poststep changes values at the END of intervals while prestep changes at the BEGINNING", "Notes that N points are converted to 2N-1 (or 2N+1 as documented) points forming a step function when connected linearly", "Mentions the edge case handling where N=0 results in length-0 arrays rather than following the formula literally", "Explains that the function accepts multiple y arrays via *args that must match x in length", "Notes that results can be unpacked as x_out, y1_out, ..., yp_out" ], "key_files": [ "lib/matplotlib/cbook.py" ], "source_doc": "[docstring: lib/matplotlib/cbook.py] lib.matplotlib.cbook.pts_to_poststep\nConvert continuous line to post-steps.\n\n Given a set of ``N`` points convert to ``2N + 1`` points, which when\n connected linearly give a step function which changes values at the end of\n the intervals.\n\n Parameters\n ----------\n x : array\n The x location of the steps. May be empty.\n\n y1, ..., yp : array\n y arrays to be turned into steps; all must be the same length as ``x``.\n\n Returns\n -------\n array\n The x and y values converted to steps in the same order as the input;\n can be unpacked as ``x_out, y1_out, ..., yp_out``. If the input is\n length ``N``, each of these arrays will be length ``2N + 1``. For\n ``N=0``, the length will be 0.\n\n Examples\n --------\n >>> x_s, y1_s, y2_s = pts_to_poststep(x, y1, y2)", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_03", "repo": "matplotlib", "question": "Where are the caveats and constraints around `bbox_to_anchor` and `bbox_transform` documented in the inset locator functions?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "When using `bbox_to_anchor` in `zoomed_inset_axes`, the documentation strongly recommends also specifying `bbox_transform`, noting that it 'almost always makes sense' to do so. The recommended transform in this case is often `parent_axes.transAxes` (the axes transform). Conversely, when specifying the axes- or figure-transform as `bbox_transform` without providing `bbox_to_anchor`, users should be aware that the default `bbox_to_anchor` will be `parent_axes.bbox`, whose units are in display (pixel) coordinates, creating a mismatch. Additionally, when `bbox_to_anchor` is specified as a 2-tuple [left, bottom], it cannot be used if the kwargs *width* and/or *height* are specified in relative units. The `borderpad` parameter uses axes font size as its unit, so with a default font size of 10 points, the default `borderpad = 0.5` equals 5 points of padding.", "rubric": [ "Mentions that when using `bbox_to_anchor` with `zoomed_inset_axes` or `inset_axes`, the documentation recommends also specifying `bbox_transform` ('it almost always makes sense')", "Identifies that the recommended transform is often `parent_axes.transAxes`", "Notes the mismatch issue: specifying axes/figure transform as `bbox_transform` without `bbox_to_anchor` defaults to `parent_axes.bbox`, which is in display/pixel coordinates", "Explains that a 2-tuple `bbox_to_anchor` (left, bottom) cannot be used when width and/or height are specified in relative units (percentage strings)", "Explains that `borderpad` uses axes font size as its unit, so with a default font size of 10 points, the default borderpad of 0.5 equals 5 points of padding" ], "key_files": [ "lib/mpl_toolkits/axes_grid1/inset_locator.py" ], "source_doc": "[docstring: lib/mpl_toolkits/axes_grid1/inset_locator.py] lib.mpl_toolkits.axes_grid1.inset_locator.zoomed_inset_axes\nCreate an anchored inset axes by scaling a parent axes. For usage, also see\n :doc:`the examples `.\n\n Parameters\n ----------\n parent_axes : `~matplotlib.axes.Axes`\n Axes to place the inset axes.\n\n zoom : float\n Scaling factor of the data axes. *zoom* > 1 will enlarge the\n coordinates (i.e., \"zoomed in\"), while *zoom* < 1 will shrink the\n coordinates (i.e., \"zoomed out\").\n\n loc : str, default: 'upper right'\n Location to place the inset axes. Valid locations are\n 'upper left', 'upper center', 'upper right',\n 'center left', 'center', 'center right',\n 'lower left', 'lower center', 'lower right'.\n For backward compatibility, numeric values are accepted as well.\n See the parameter *loc* of `.Legend` for details.\n\n bbox_to_anchor : tuple or `~matplotlib.transforms.BboxBase`, optional\n Bbox that the inset axes will be anchored to. If None,\n *parent_axes.bbox* is used. If a tuple, can be either\n [left, bottom, width, height], or [left, bottom].\n If the kwargs *width* and/or *height* are specified in relative units,\n the 2-tuple [left, bottom] cannot be used. Note that\n the units of the bounding box are determined through the transform\n in use. When using *bbox_to_anchor* it almost always makes sense to\n also specify a *bbox_transform*. This might often be the axes transform\n *parent_axes.transAxes*.\n\n bbox_transform : `~matplotlib.transforms.Transform`, optional\n Transformation for the bbox that contains the inset axes.\n If None, a `.transforms.IdentityTransform` is used (i.e. pixel\n coordinates). This is useful when not providing any argument to\n *bbox_to_anchor*. When using *bbox_to_anchor* it almost always makes\n sense to also specify a *bbox_transform*. This might often be the\n axes transform *parent_axes.transAxes*. Inversely, when specifying\n the axes- or figure-transform here, be aware that not specifying\n *bbox_to_anchor* will use *parent_axes.bbox*, the units of which are\n in display (pixel) coordinates.\n\n axes_class : `~matplotlib.axes.Axes` type, default: `.HostAxes`\n The type of the newly created inset axes.\n\n axes_kwargs : dict, optional\n Keyword arguments to pass to the constructor of the inset axes.\n Valid arguments include:\n\n %(Axes:kwdoc)s\n\n borderpad : float, default: 0.5\n Padding between inset axes and the bbox_to_anchor.\n The units are axes font size, i.e. for a default font size of 10 points\n *borderpad = 0.5* is equivalent to a padding of 5 points.\n\n Returns\n -------\n inset_axes : *axes_class*\n Inset axes object created.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_04", "repo": "matplotlib", "question": "How does ExtremeFinderFixed determine which bounding box to return compared to its parent class?", "category": "how", "sub_type": "system_design", "gold_answer": "ExtremeFinderFixed works by always returning the same bounding box regardless of any other input or state. It is a subclass designed to provide a fixed, unchanging bounding box. The bounding box is specified at initialization as a tuple of four floats (extremes parameter), and this exact bounding box is what the helper always returns whenever queried. This behavior contrasts with a dynamic extreme finder that might calculate bounds based on data or view limits - ExtremeFinderFixed simply bypasses any computation and consistently returns the pre-configured extremes.", "rubric": [ "Mentions that ExtremeFinderFixed always returns the same fixed bounding box regardless of input", "Explains that the bounding box is specified at initialization via an extremes tuple of four floats", "Mentions it is a subclass of ExtremeFinderSimple", "Explains that the parent class (ExtremeFinderSimple) dynamically computes bounds by sampling a grid of points and transforming them", "Notes that ExtremeFinderFixed overrides _find_transformed_bbox to simply return the stored Bbox without performing any computation" ], "key_files": [ "lib/mpl_toolkits/axisartist/floating_axes.py" ], "source_doc": "[docstring: lib/mpl_toolkits/axisartist/floating_axes.py] lib.mpl_toolkits.axisartist.floating_axes.ExtremeFinderFixed\nlib.mpl_toolkits.axisartist.floating_axes.ExtremeFinderFixed.__init__:\n This subclass always returns the same bounding box.\n\n Parameters\n ----------\n extremes : (float, float, float, float)\n The bounding box that this helper always returns.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_05", "repo": "matplotlib", "question": "What does ExtremeFinderSimple do, and how does it determine the padding for its bounding box approximation?", "category": "what", "sub_type": "concept_definition", "gold_answer": "ExtremeFinderSimple computes an approximation of the bounding box by sampling nx * ny equispaced points in the input box, applying the transform to find points with extremal coordinates, and then adding padding to account for finite sampling. The padding is calculated by expanding the span covered by the extremal coordinates by fractions of 1/nx and 1/ny, since each sampling step covers a relative range of 1/nx or 1/ny. The intended use case is to have the input box (x1, y1, x2, y2) in axes coordinates, with transform_xy being the transform from axes coordinates to data coordinates, so the method returns the range of data coordinates that span the actual axes.", "rubric": [ "Explains that ExtremeFinderSimple computes an approximation of the bounding box by sampling nx*ny equispaced points in the input box", "Mentions that the transform is applied to the sampled points to find extremal coordinates", "Explains that padding is added by expanding the span by fractions of 1/nx and 1/ny to account for finite sampling", "Describes the intended use case: input box in axes coordinates, transform_xy converts axes to data coordinates, returns data coordinate range spanning the axes" ], "key_files": [ "lib/mpl_toolkits/axisartist/grid_finder.py" ], "source_doc": "[docstring: lib/mpl_toolkits/axisartist/grid_finder.py] lib.mpl_toolkits.axisartist.grid_finder.ExtremeFinderSimple\nlib.mpl_toolkits.axisartist.grid_finder.ExtremeFinderSimple:\n A helper class to figure out the range of grid lines that need to be drawn.\n\nlib.mpl_toolkits.axisartist.grid_finder.ExtremeFinderSimple.__init__:\n Parameters\n ----------\n nx, ny : int\n The number of samples in each direction.\n\nlib.mpl_toolkits.axisartist.grid_finder.ExtremeFinderSimple.__call__:\n Compute an approximation of the bounding box obtained by applying\n *transform_xy* to the box delimited by ``(x1, y1, x2, y2)``.\n\n The intended use is to have ``(x1, y1, x2, y2)`` in axes coordinates,\n and have *transform_xy* be the transform from axes coordinates to data\n coordinates; this method then returns the range of data coordinates\n that span the actual axes.\n\n The computation is done by sampling ``nx * ny`` equispaced points in\n the ``(x1, y1, x2, y2)`` box and finding the resulting points with\n extremal coordinates; then adding some padding to take into account the\n finite sampling.\n\n As each sampling step covers a relative range of ``1/nx`` or ``1/ny``,\n the padding is computed by expanding the span covered by the extremal\n coordinates by these fractions.\n\nlib.mpl_toolkits.axisartist.grid_finder.ExtremeFinderSimple._find_transformed_bbox:\n Compute an approximation of the bounding box obtained by applying\n *trans* to *bbox*.\n\n See ``__call__`` for details; this method performs similar\n calculations, but using a different representation of the arguments and\n return value.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_06", "repo": "matplotlib", "question": "Why does Line3D need separate get_data_3d and set_data_3d methods instead of just using the inherited get_data and set_data from Line2D?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The documentation explicitly warns users that `get_data`, `get_xdata`, and `get_ydata` (inherited from Line2D) return the x- and y-coordinates of the **projected 2D line**, not the actual x- and y-data of the 3D line. This is why `get_data_3d` and `set_data_3d` exist as separate methods \u2014 they are the correct way to obtain and set the true 3D data. The design rationale is that Line3D inherits from Line2D, and the inherited 2D accessor methods operate on the projected (rendered) coordinates rather than the original 3D spatial data. Without this documentation note, users would naturally assume that `get_data` or `get_xdata` would return the original data they passed in, leading to subtle bugs when working with 3D line data. The distinction exists because the 3D-to-2D projection is an internal rendering step, and the projected values are what Line2D uses for actual drawing, while the original 3D data must be accessed through the dedicated 3D methods.", "rubric": [ "Explains that Line3D inherits from Line2D and the inherited methods (get_data, get_xdata, get_ydata) return projected 2D coordinates, not the original 3D data", "Mentions that during drawing/rendering, the 3D data is projected to 2D via proj3d and then set_data(xs, ys) is called with the projected values", "Notes that get_data_3d returns the actual 3D vertex data stored in _verts3d, which holds the original x, y, z coordinates", "Identifies that without the dedicated 3D methods, users would get projected/rendered coordinates instead of their original input data" ], "key_files": [ "lib/mpl_toolkits/mplot3d/art3d.py" ], "source_doc": "[docstring: lib/mpl_toolkits/mplot3d/art3d.py] lib.mpl_toolkits.mplot3d.art3d.Line3D\nlib.mpl_toolkits.mplot3d.art3d.Line3D:\n 3D line object.\n\n .. note:: Use `get_data_3d` to obtain the data associated with the line.\n `~.Line2D.get_data`, `~.Line2D.get_xdata`, and `~.Line2D.get_ydata` return\n the x- and y-coordinates of the projected 2D-line, not the x- and y-data of\n the 3D-line. Similarly, use `set_data_3d` to set the data, not\n `~.Line2D.set_data`, `~.Line2D.set_xdata`, and `~.Line2D.set_ydata`.\n\nlib.mpl_toolkits.mplot3d.art3d.Line3D.__init__:\n Parameters\n ----------\n xs : array-like\n The x-data to be plotted.\n ys : array-like\n The y-data to be plotted.\n zs : array-like\n The z-data to be plotted.\n *args, **kwargs\n Additional arguments are passed to `~matplotlib.lines.Line2D`.\n\nlib.mpl_toolkits.mplot3d.art3d.Line3D.set_3d_properties:\n Set the *z* position and direction of the line.\n\n Parameters\n ----------\n zs : float or array of floats\n The location along the *zdir* axis in 3D space to position the\n line.\n zdir : {'x', 'y', 'z'}\n Plane to plot line orthogonal to. Default: 'z'.\n See `.get_dir_vector` for a description of the values.\n axlim_clip : bool, default: False\n Whether to hide lines with an endpoint outside the axes view limits.\n\n .. versionadded:: 3.10\n\nlib.mpl_toolkits.mplot3d.art3d.Line3D.set_data_3d:\n Set the x, y and z data\n\n Parameters\n ----------\n x : array-like\n The x-data to be plotted.\n y : array-like\n The y-data to be plotted.\n z : array-like\n The z-data to be plotted.\n\n Notes\n -----\n Accepts x, y, z arguments or a single array-like (x, y, z)\n\nlib.mpl_toolkits.mplot3d.art3d.Line3D.get_data_3d:\n Get the current data\n\n Returns\n -------\n verts3d : length-3 tuple or array-like\n The current data as a tuple or array-like.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_07", "repo": "matplotlib", "question": "Where are the 3D axis tick position, label position, pane color, and label rotation controlled, and what values do they accept?", "category": "where", "sub_type": "feature_location", "gold_answer": "In matplotlib's 3D axis system, the `set_ticks_position` and `set_label_position` methods on `lib/mpl_toolkits/mplot3d/axis3d.py`'s Axis class control where ticks and labels appear. The ticks position specifically controls the position of the 'bolded axis lines, ticks, and tick labels', while the label position controls the position of the axis label. Both accept the same set of position values: 'lower', 'upper', 'both', 'default', or 'none'. The `set_rotate_label` method controls label rotation and accepts True, False, or None, where None triggers automatic rotation behavior \u2014 the label will be rotated if it is longer than 4 characters. The `set_pane_color` method accepts a color and an optional alpha parameter, where if alpha is None, the alpha value will be based on the provided color.", "rubric": [ "Identifies that set_ticks_position and set_label_position are in the 3D Axis class (mplot3d/axis3d.py)", "States that set_ticks_position controls the position of bolded axis lines, ticks, and tick labels", "States that set_label_position controls the position of the axis label", "Lists the valid position values: 'lower', 'upper', 'both', 'default', or 'none' (same for both methods)", "Explains that set_rotate_label accepts True, False, or None, where None causes automatic rotation if the label is longer than 4 characters", "Explains that set_pane_color accepts a color and an optional alpha parameter, where if alpha is None it is derived from the color" ], "key_files": [ "lib/mpl_toolkits/mplot3d/axis3d.py" ], "source_doc": "[docstring: lib/mpl_toolkits/mplot3d/axis3d.py] lib.mpl_toolkits.mplot3d.axis3d.Axis\nlib.mpl_toolkits.mplot3d.axis3d.Axis:\n An Axis class for the 3D plots.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.set_ticks_position:\n Set the ticks position.\n\n Parameters\n ----------\n position : {'lower', 'upper', 'both', 'default', 'none'}\n The position of the bolded axis lines, ticks, and tick labels.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.get_ticks_position:\n Get the ticks position.\n\n Returns\n -------\n str : {'lower', 'upper', 'both', 'default', 'none'}\n The position of the bolded axis lines, ticks, and tick labels.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.set_label_position:\n Set the label position.\n\n Parameters\n ----------\n position : {'lower', 'upper', 'both', 'default', 'none'}\n The position of the axis label.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.get_label_position:\n Get the label position.\n\n Returns\n -------\n str : {'lower', 'upper', 'both', 'default', 'none'}\n The position of the axis label.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.set_pane_color:\n Set pane color.\n\n Parameters\n ----------\n color : :mpltype:`color`\n Color for axis pane.\n alpha : float, optional\n Alpha value for axis pane. If None, base it on *color*.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.set_rotate_label:\n Whether to rotate the axis label: True, False or None.\n If set to None the label will be rotated if longer than 4 chars.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis._get_axis_line_edge_points:\n Get the edge points for the black bolded axis line.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis._get_tickdir:\n Get the direction of the tick.\n\n Parameters\n ----------\n position : str, optional : {'upper', 'lower', 'default'}\n The position of the axis.\n\n Returns\n -------\n tickdir : int\n Index which indicates which coordinate the tick line will\n align with.\n\nlib.mpl_toolkits.mplot3d.axis3d.Axis.draw_pane:\n Draw pane.\n\n Parameters\n ----------\n renderer : `~matplotlib.backend_bases.RendererBase` subclass", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_09", "repo": "matplotlib", "question": "What is the default value of `_rasterization_zorder` on Axes, and what does that imply for artist rasterization during drawing?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "In matplotlib 1.2.x, the `rasterization_zorder` property on Axes changed its default value from -30000.0 to None. Previously, with the default of -30000.0, artists with a zorder below that threshold would automatically be rasterized. After the change, the default of None means no artists will be rasterized unless `set_rasterization_zorder` is explicitly called with a specific zorder value. This change depends on the `rasterization_zorder` property of the `matplotlib.axes.Axes` class and the `set_rasterization_zorder` method. The practical implication is that users who previously relied on the implicit rasterization of very-low-zorder artists (below -30000.0) would need to explicitly opt in to rasterization behavior after this API change.", "rubric": [ "States that _rasterization_zorder defaults to None", "Explains that when set to None, no artists are automatically rasterized based on zorder", "Mentions that set_rasterization_zorder must be explicitly called to enable zorder-based rasterization", "Describes how the draw logic checks if rasterization_zorder is not None and compares artist zorder values to determine which artists to rasterize", "Notes that artists with zorder below the threshold are rasterized when a non-None value is set" ], "key_files": [ "doc/api/prev_api_changes/api_changes_1.2.x.rst" ], "source_doc": "[doc_file: doc/api/prev_api_changes/api_changes_1.2.x.rst] API Changes in 1.2.x\n* The ``classic`` option of the rc parameter ``toolbar`` is deprecated\n and will be removed in the next release.\n\n* The ``matplotlib.cbook.isvector`` method has been removed since it\n is no longer functional.\n\n* The ``rasterization_zorder`` property on `~matplotlib.axes.Axes` sets a\n zorder below which artists are rasterized. This has defaulted to\n -30000.0, but it now defaults to *None*, meaning no artists will be\n rasterized. In order to rasterize artists below a given zorder\n value, `.set_rasterization_zorder` must be explicitly called.\n\n* In :meth:`~matplotlib.axes.Axes.scatter`, and `~.pyplot.scatter`,\n when specifying a marker using a tuple, the angle is now specified\n in degrees, not radians.\n\n* Using :meth:`~matplotlib.axes.Axes.twinx` or\n :meth:`~matplotlib.axes.Axes.twiny` no longer overrides the current locaters\n and formatters on the axes.\n\n* In :meth:`~matplotlib.axes.Axes.contourf`, the handling of the *extend*\n kwarg has changed. Formerly, the extended ranges were mapped\n after to 0, 1 after being normed, so that they always corresponded\n to the extreme values of the colormap. Now they are mapped\n outside this range so that they correspond to the special\n colormap values determined by the\n :meth:`~matplotlib.colors.Colormap.set_under` and\n :meth:`~matplotlib.colors.Colormap.set_over` methods, which\n default to the colormap end points.\n\n* The new rc parameter ``savefig.format`` replaces ``cairo.format`` and\n ``savefig.extension``, and sets the default file format used by\n :meth:`matplotlib.figure.Figure.savefig`.\n\n* In :func:`.pyplot.pie` and :meth:`.axes.Axes.pie`, one can now set the radius\n of the pie; setting the *radius* to 'None' (the default value), will result\n in a pie with a radius of 1 as before.\n\n* Use of ``matplotlib.projections.projection_factory`` is now deprecated\n in favour of axes class identification using\n ``matplotlib.projections.process_projection_requirements`` followed by\n direct axes class invocation (at the time of writing, functions which do this\n are: :meth:`~matplotlib.figure.Figure.add_axes`,\n :meth:`~matplotlib.figure.Figure.add_subplot` and\n :meth:`~matplotlib.figure.Figure.gca`). Therefore::\n\n\n key = figure._make_key(*args, **kwargs)\n ispolar = kwargs.pop('polar', False)\n projection = kwargs.pop('projection', None)\n if ispolar:\n if projection is not None and projection != 'polar':\n raise ValueError('polar and projection args are inconsistent')\n projection = 'polar'\n ax = projection_factory(projection, self, rect, **kwargs)\n key = self._make_key(*args, **kwargs)\n\n # is now\n\n projection_class, kwargs, key = \\\n process_projection_requirements(self, *args, **kwargs)\n ax = projection_class(self, rect, **kwargs)\n\n This change means that third party objects can expose themselves as\n Matplotlib axes by providing a ``_as_mpl_axes`` method. See\n :mod:`matplotlib.projections` for more detail.\n\n* A new keyword *extendfrac* in :meth:`~matplotlib.pyplot.colorbar` and\n :class:`~matplotlib.colorbar.ColorbarBase` allows one to control the size of\n the triangular minimum and maximum extensions on colorbars.\n\n* A new keyword *capthick* in :meth:`~matplotlib.pyplot.errorbar` has been\n added as an intuitive alias to the *markeredgewidth* and *mew* keyword\n arguments, which indirectly controlled the thickness of the caps on\n the errorbars. For backwards compatibility, specifying either of the\n original keyword arguments will override any value provided by\n *capthick*.\n\n* Transform subclassing behaviour is now subtly changed. If your transform\n implements a non-affine transformation, then it should override the\n ``transform_non_affine`` method, rather than the generic ``transform`` method.\n Previously transforms would define ``transform`` and then copy the\n method into ``transform_non_affine``::\n\n class MyTransform(mtrans.Transform):\n def transform(self, xy):\n ...\n transform_non_affine = transform\n\n\n This approach will no longer function correctly and should be changed to::\n\n class MyTransform(mtrans.Transform):\n def transform_non_affine(self, xy):\n ...\n\n\n* Artists no longer have ``x_isdata`` or ``y_isdata`` attributes; instead\n any artist's transform can be interrogated with\n ``artist_instance.get_transform().contains_branch(ax.transData)``\n\n* Lines added to an axes now take into account their transform when updating the\n data and view limits. This means transforms can now be used as a pre-transform.\n For instance::\n\n >>> import matplotlib.pyplot as plt\n >>> import matplotlib.transforms as mtrans\n >>> ax = plt.axes()\n >>> ax.plot(range(10), transform=mtrans.Affine2D().scale(10) + ax.transData)\n >>> print(ax.viewLim)\n Bbox('array([[ 0., 0.],\\n [ 90., 90.]])')\n\n* One can now easily get a transform which goes from one transform's coordinate\n system to another, in an optimized way, using the new subtract method on a\n transform. For instance, to go from data coordinates to axes coordinates::\n\n >>> import matplotlib.pyplot as plt\n >>> ax = plt.axes()\n >>> data2ax = ax.transData - ax.transAxes\n >>> print(ax.transData.depth, ax.transAxes.depth)\n 3, 1\n >>> print(data2ax.depth)\n 2\n\n for versions before 1.2 this could only be achieved in a sub-optimal way,\n using ``ax.transData + ax.transAxes.inverted()`` (depth is a new concept,\n but had it existed it would return 4 for this example).\n\n* ``twinx`` and ``twiny`` now returns an instance of SubplotBase if\n parent axes is an instance of SubplotBase.\n\n* All Qt3-based backends are now deprecated due to the lack of py3k bindings.\n Qt and QtAgg backends will continue to work in v1.2.x for py2.6\n and py2.7. It is anticipated that the Qt3 support will be completely\n removed for the next release.\n\n* ``matplotlib.colors.ColorConverter``,\n :class:`~matplotlib.colors.Colormap` and\n :class:`~matplotlib.colors.Normalize` now subclasses ``object``\n\n* ContourSet instances no longer have a ``transform`` attribute. Instead,\n access the transform with the ``get_transform`` method.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_10", "repo": "matplotlib", "question": "Why were the `matplotlib.compat.subprocess` and `matplotlib.backends.wx_compat` modules deprecated in the 3.0 release?", "category": "why", "sub_type": "performance", "gold_answer": "The `matplotlib.compat.subprocess` module was deprecated because it was a Python 2 workaround, and all the functionality it provided can now be found in the Python 3 standard library `subprocess` module. Similarly, `matplotlib.backends.wx_compat` was deprecated because Python 3 is only compatible with wxPython 4, so there was no longer a need to maintain support for wxPython 3 or earlier versions. These deprecations were driven by the elimination of Python 2 compatibility layers that became unnecessary once Matplotlib required Python 3, where the standard library already provided the needed functionality. The performance consideration here is the reduction of unnecessary abstraction layers and compatibility shims that added overhead without providing benefit in a Python 3-only environment.", "rubric": [ "Explains that matplotlib.compat.subprocess was a Python 2 workaround whose functionality is available in the Python 3 standard library subprocess module", "Explains that matplotlib.backends.wx_compat was deprecated because Python 3 only supports wxPython 4, making wxPython 3 compatibility unnecessary", "Identifies the broader context that these deprecations were driven by dropping Python 2 support in Matplotlib 3.0", "Mentions the benefit of removing unnecessary compatibility/abstraction layers that no longer serve a purpose in a Python 3-only environment" ], "key_files": [ "doc/api/prev_api_changes/api_changes_3.0.0.rst" ], "source_doc": "[doc_file: doc/api/prev_api_changes/api_changes_3.0.0.rst] Deprecations\nModules\n```````\nThe following modules are deprecated:\n\n- ``matplotlib.compat.subprocess``. This was a python 2 workaround, but all\n the functionality can now be found in the python 3 standard library\n :mod:`subprocess`.\n- ``matplotlib.backends.wx_compat``. Python 3 is only compatible with\n wxPython 4, so support for wxPython 3 or earlier can be dropped.\n\nClasses, methods, functions, and attributes\n```````````````````````````````````````````\n\nThe following classes, methods, functions, and attributes are deprecated:\n\n- ``RcParams.msg_depr``, ``RcParams.msg_depr_ignore``,\n ``RcParams.msg_depr_set``, ``RcParams.msg_obsolete``,\n ``RcParams.msg_backend_obsolete``\n- ``afm.parse_afm``\n- ``backend_pdf.PdfFile.texFontMap``\n- ``backend_pgf.get_texcommand``\n- ``backend_ps.get_bbox``\n- ``backend_qt5.FigureCanvasQT.keyAutoRepeat`` (directly check\n ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to\n handle autorepeated key presses).\n- ``backend_qt5.error_msg_qt``, ``backend_qt5.exception_handler``\n- ``backend_wx.FigureCanvasWx.macros``\n- ``backends.pylab_setup``\n- ``cbook.GetRealpathAndStat``, ``cbook.Locked``\n- ``cbook.is_numlike`` (use ``isinstance(..., numbers.Number)`` instead),\n ``cbook.listFiles``, ``cbook.unicode_safe``\n- ``container.Container.set_remove_method``,\n- ``contour.ContourLabeler.cl``, ``.cl_xy``, and ``.cl_cvalues``\n- ``dates.DateFormatter.strftime_pre_1900``, ``dates.DateFormatter.strftime``\n- ``font_manager.TempCache``\n- ``image._ImageBase.iterpnames``, use the ``interpolation_names`` property\n instead. (this affects classes that inherit from ``_ImageBase`` including\n `.FigureImage`, `.BboxImage`, and `.AxesImage`)\n- ``mathtext.unichr_safe`` (use ``chr`` instead)\n- ``patches.Polygon.xy``\n- ``table.Table.get_child_artists`` (use ``get_children`` instead)\n- ``testing.compare.ImageComparisonTest``, ``testing.compare.compare_float``\n- ``testing.decorators.CleanupTest``,\n ``testing.decorators.skip_if_command_unavailable``\n- ``FigureCanvasQT.keyAutoRepeat`` (directly check\n ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to\n handle autorepeated key presses)\n- ``FigureCanvasWx.macros``\n- ``_ImageBase.iterpnames``, use the ``interpolation_names`` property instead.\n (this affects classes that inherit from ``_ImageBase`` including\n `.FigureImage`, `.BboxImage`, and `.AxesImage`)\n- ``patches.Polygon.xy``\n- ``texmanager.dvipng_hack_alpha``\n- ``text.Annotation.arrow``\n- ``Legend.draggable()``, in favor of `.Legend.set_draggable()`\n (``Legend.draggable`` may be reintroduced as a property in future releases)\n- ``textpath.TextToPath.tex_font_map``\n- ``matplotlib.cbook.deprecation.mplDeprecation`` will be removed\n in future versions. It is just an alias for\n ``matplotlib.cbook.deprecation.MatplotlibDeprecationWarning``. Please\n use ``matplotlib.cbook.MatplotlibDeprecationWarning`` directly if necessary.\n- The ``matplotlib.cbook.Bunch`` class has been deprecated. Instead, use\n `types.SimpleNamespace` from the standard library which provides the same\n functionality.\n- ``Axes.mouseover_set`` is now a frozenset, and deprecated. Directly\n manipulate the artist's ``.mouseover`` attribute to change their mouseover\n status.\n\nThe following keyword arguments are deprecated:\n\n- passing ``verts`` to ``Axes.scatter`` (use ``marker`` instead)\n- passing ``obj_type`` to ``cbook.deprecated``\n\nThe following call signatures are deprecated:\n\n- passing a ``wx.EvtHandler`` as first argument to ``backend_wx.TimerWx``\n\n\nrcParams\n````````\n\nThe following rcParams are deprecated:\n\n- ``examples.directory`` (use ``datapath`` instead)\n- ``pgf.debug`` (the pgf backend relies on logging)\n- ``text.latex.unicode`` (always True now)\n\n\nmarker styles\n`````````````\n- Using ``(n, 3)`` as marker style to specify a circle marker is deprecated. Use\n ``\"o\"`` instead.\n- Using ``([(x0, y0), (x1, y1), ...], 0)`` as marker style to specify a custom\n marker path is deprecated. Use ``[(x0, y0), (x1, y1), ...]`` instead.\n\n\nDeprecation of ``LocatableAxes`` in toolkits\n````````````````````````````````````````````\n\nThe ``LocatableAxes`` classes in toolkits have been deprecated. The base `~.axes.Axes`\nclasses provide the same functionality to all subclasses, thus these mixins are\nno longer necessary. Related functions have also been deprecated. Specifically:\n\n* ``mpl_toolkits.axes_grid1.axes_divider.LocatableAxesBase``: no specific\n replacement; use any other ``Axes``-derived class directly instead.\n* ``mpl_toolkits.axes_grid1.axes_divider.locatable_axes_factory``: no specific\n replacement; use any other ``Axes``-derived class directly instead.\n* ``mpl_toolkits.axes_grid1.axes_divider.Axes``: use\n `mpl_toolkits.axes_grid1.mpl_axes.Axes` directly.\n* ``mpl_toolkits.axes_grid1.axes_divider.LocatableAxes``: use\n `mpl_toolkits.axes_grid1.mpl_axes.Axes` directly.\n* ``mpl_toolkits.axisartist.axes_divider.Axes``: use\n `mpl_toolkits.axisartist.axislines.Axes` directly.\n* ``mpl_toolkits.axisartist.axes_divider.LocatableAxes``: use\n `mpl_toolkits.axisartist.axislines.Axes` directly.", "verification_verdict": "warn", "verification_issues": [ "The claim about 'performance consideration' and 'reduction of unnecessary abstraction layers and compatibility shims that added overhead' is not supported by the documentation. The documentation only mentions these were Python 2 workarounds, not that they caused performance overhead. This is an unsupported extrapolation.", "The statement 'once Matplotlib required Python 3' is a plausible inference but not explicitly stated in the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "matplotlib_gen_08", "repo": "matplotlib", "question": "How does the spectral helper function handle two-sided frequency ordering and one-sided PSD scaling in mlab?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "In matplotlib 0.98.x, the functions psd(), csd(), and cohere() were changed to automatically wrap negative frequency components to the beginning of the returned arrays. This behavioral change was made to be consistent with specgram(), which already exhibited this behavior. The documentation explicitly states that the previous behavior (where negative frequency components were not wrapped to the beginning) was 'more of an oversight than a design decision' \u2014 meaning it was never intentionally designed that way, it just happened to work that way due to how the FFT results were returned without rearrangement. Additionally, the one-sided density scaling was modified to multiply by a factor of 2, and optionally scale by the sampling frequency. This scaling gives 'true values of densities that can be integrated by the returned frequency values' \u2014 meaning if you numerically integrate the PSD over the frequency array, you get the correct total power. This approach also improved MATLAB compatibility.", "rubric": [ "Negative frequency components are wrapped/rolled to the beginning of the array using np.roll with -freqcenter for twosided spectra, centering the frequency range at zero", "The one-sided scaling_factor is 2.0, which is multiplied into the PSD result for all frequency bins except DC and Nyquist", "When scale_by_freq is True, the result is additionally divided by the sampling frequency Fs for MATLAB compatibility, giving densities in units of 1/Hz that can be integrated over the returned frequency values", "This wrapping behavior makes psd/csd/cohere consistent with specgram, which already exhibited this behavior", "For onesided spectra with an even pad_to, the last frequency value is negated (freqs[-1] *= -1) to get the correct sign" ], "key_files": [ "doc/api/prev_api_changes/api_changes_0.98.x.rst" ], "source_doc": "[doc_file: doc/api/prev_api_changes/api_changes_0.98.x.rst] Changes for 0.98.x\n* ``psd()``, ``csd()``, and ``cohere()`` will now automatically wrap negative\n frequency components to the beginning of the returned arrays.\n This is much more sensible behavior and makes them consistent\n with ``specgram()``. The previous behavior was more of an oversight\n than a design decision.\n\n* Added new keyword parameters *nonposx*, *nonposy* to\n :class:`matplotlib.axes.Axes` methods that set log scale\n parameters. The default is still to mask out non-positive\n values, but the kwargs accept 'clip', which causes non-positive\n values to be replaced with a very small positive value.\n\n* Added new :func:`matplotlib.pyplot.fignum_exists` and\n :func:`matplotlib.pyplot.get_fignums`; they merely expose\n information that had been hidden in ``matplotlib._pylab_helpers``.\n\n* Deprecated numerix package.\n\n* Added new :func:`matplotlib.image.imsave` and exposed it to the\n :mod:`matplotlib.pyplot` interface.\n\n* Remove support for pyExcelerator in exceltools -- use xlwt\n instead\n\n* Changed the defaults of acorr and xcorr to use usevlines=True,\n maxlags=10 and normed=True since these are the best defaults\n\n* Following keyword parameters for :class:`matplotlib.legend.Legend` are now\n deprecated and new set of parameters are introduced. The new parameters\n are given as a fraction of the font-size. Also, *scatteryoffsets*,\n *fancybox* and *columnspacing* are added as keyword parameters.\n\n ================ ================\n Deprecated New\n ================ ================\n pad borderpad\n labelsep labelspacing\n handlelen handlelength\n handlestextsep handletextpad\n axespad borderaxespad\n ================ ================\n\n* Removed the configobj and experimental traits rc support\n\n* Modified :func:`matplotlib.mlab.psd`, :func:`matplotlib.mlab.csd`,\n :func:`matplotlib.mlab.cohere`, and :func:`matplotlib.mlab.specgram`\n to scale one-sided densities by a factor of 2. Also, optionally\n scale the densities by the sampling frequency, which gives true values\n of densities that can be integrated by the returned frequency values.\n This also gives better MATLAB compatibility. The corresponding\n :class:`matplotlib.axes.Axes` methods and :mod:`matplotlib.pyplot`\n functions were updated as well.\n\n* Font lookup now uses a nearest-neighbor approach rather than an\n exact match. Some fonts may be different in plots, but should be\n closer to what was requested.\n\n* :meth:`matplotlib.axes.Axes.set_xlim`,\n :meth:`matplotlib.axes.Axes.set_ylim` now return a copy of the\n ``viewlim`` array to avoid modify-in-place surprises.\n\n* ``matplotlib.afm.AFM.get_fullname`` and\n ``matplotlib.afm.AFM.get_familyname`` no longer raise an\n exception if the AFM file does not specify these optional\n attributes, but returns a guess based on the required FontName\n attribute.\n\n* Changed precision kwarg in :func:`matplotlib.pyplot.spy`; default is\n 0, and the string value 'present' is used for sparse arrays only to\n show filled locations.\n\n* :class:`matplotlib.collections.EllipseCollection` added.\n\n* Added ``angles`` kwarg to :func:`matplotlib.pyplot.quiver` for more\n flexible specification of the arrow angles.\n\n* Deprecated (raise NotImplementedError) all the mlab2 functions from\n :mod:`matplotlib.mlab` out of concern that some of them were not\n clean room implementations.\n\n* Methods :meth:`matplotlib.collections.Collection.get_offsets` and\n :meth:`matplotlib.collections.Collection.set_offsets` added to\n :class:`~matplotlib.collections.Collection` base class.\n\n* ``matplotlib.figure.Figure.figurePatch`` renamed\n ``matplotlib.figure.Figure.patch``;\n ``matplotlib.axes.Axes.axesPatch`` renamed\n ``matplotlib.axes.Axes.patch``;\n ``matplotlib.axes.Axes.axesFrame`` renamed\n ``matplotlib.axes.Axes.frame``.\n ``matplotlib.axes.Axes.get_frame``, which returns\n ``matplotlib.axes.Axes.patch``, is deprecated.\n\n* Changes in the :class:`matplotlib.contour.ContourLabeler` attributes\n (:func:`matplotlib.pyplot.clabel` function) so that they all have a\n form like ``.labelAttribute``. The three attributes that are most\n likely to be used by end users, ``.cl``, ``.cl_xy`` and\n ``.cl_cvalues`` have been maintained for the moment (in addition to\n their renamed versions), but they are deprecated and will eventually\n be removed.\n\n* Moved several functions in :mod:`matplotlib.mlab` and\n :mod:`matplotlib.cbook` into a separate module\n ``matplotlib.numerical_methods`` because they were unrelated to\n the initial purpose of mlab or cbook and appeared more coherent\n elsewhere.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_03", "repo": "sympy", "question": "Where does the quantum entropy function get its input from, and where does it branch based on input type?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "The `entropy` function in `sympy/physics/quantum/density.py` can accept density matrices in four different forms: a `Density` instance, a SymPy matrix (`sympy.Matrix`), a scipy sparse matrix (`scipy.sparse`), or a numpy array (`numpy.ndarray`). The function computes the entropy using the formula -Tr(density*ln(density)), and it does so specifically by using the eigenvalue decomposition of the density matrix. This means the computation relies on finding eigenvalues rather than directly computing the matrix logarithm and trace.", "rubric": [ "Mentions that the entropy function accepts a Density instance as input", "Mentions that it accepts a SymPy Matrix (sympy.Matrix) as input", "Mentions that it accepts a scipy sparse matrix as input", "Mentions that it accepts a numpy ndarray as input", "Explains that the computation uses -Tr(density*ln(density))", "Explains that the actual computation uses eigenvalue decomposition rather than directly computing the matrix logarithm and trace" ], "key_files": [ "sympy/physics/quantum/density.py" ], "source_doc": "[docstring: sympy/physics/quantum/density.py] sympy.physics.quantum.density.entropy\nCompute the entropy of a matrix/density object.\n\n This computes -Tr(density*ln(density)) using the eigenvalue decomposition\n of density, which is given as either a Density instance or a matrix\n (numpy.ndarray, sympy.Matrix or scipy.sparse).\n\n Parameters\n ==========\n\n density : density matrix of type Density, SymPy matrix,\n scipy.sparse or numpy.ndarray\n\n Examples\n ========\n\n >>> from sympy.physics.quantum.density import Density, entropy\n >>> from sympy.physics.quantum.spin import JzKet\n >>> from sympy import S\n >>> up = JzKet(S(1)/2,S(1)/2)\n >>> down = JzKet(S(1)/2,-S(1)/2)\n >>> d = Density((up,S(1)/2),(down,S(1)/2))\n >>> entropy(d)\n log(2)/2", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_02", "repo": "sympy", "question": "Why does the WeldJoint use intermediate frames and an identity DCM constraint rather than directly constraining the parent and child body frames?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The WeldJoint is designed such that there is no relative motion between the child and parent bodies. The design rationale is that the direction cosine matrix between the attachment frames (parent_interframe and child_interframe) is specifically constrained to be the identity matrix, and the attachment points (parent_point and child_point) are constrained to be coincident. This means the joint enforces both zero relative rotation and zero relative translation between the connected frames/points. The joint has no generalized coordinates and no generalized speeds (both are empty matrices), which reflects the fundamental design choice that a weld joint has zero degrees of freedom. The intermediate frames (parent_interframe and child_interframe) exist to allow users to specify a fixed relative orientation between the parent and child bodies - the identity DCM constraint is between these intermediate frames, not necessarily between the body frames themselves. This design allows the WeldJoint to model relatively-fixed bodies that may have a constant rotational offset, as demonstrated by the example where two bodies are fixed at a quarter turn about the Y axis using a rotated intermediate frame.", "rubric": [ "Explains that the identity DCM constraint is between parent_interframe and child_interframe, not between the body frames themselves", "Notes that this design allows users to specify a fixed relative orientation/rotational offset between the parent and child bodies", "Mentions that WeldJoint has zero degrees of freedom (no generalized coordinates and no generalized speeds)", "Explains that the joint enforces both zero relative rotation and zero relative translation between the connected interframes/points", "References or describes the example where two bodies can be fixed at a constant angular offset (e.g., quarter turn about Y axis) using a rotated intermediate frame" ], "key_files": [ "sympy/physics/mechanics/joint.py" ], "source_doc": "[docstring: sympy/physics/mechanics/joint.py] sympy.physics.mechanics.joint.WeldJoint\nsympy.physics.mechanics.joint.WeldJoint:\n Weld Joint.\n\n .. raw:: html\n :file: ../../../doc/src/modules/physics/mechanics/api/WeldJoint.svg\n\n Explanation\n ===========\n\n A weld joint is defined such that there is no relative motion between the\n child and parent bodies. The direction cosine matrix between the attachment\n frame (``parent_interframe`` and ``child_interframe``) is the identity\n matrix and the attachment points (``parent_point`` and ``child_point``) are\n coincident. The page on the joints framework gives a more detailed\n explanation of the intermediate frames.\n\n Parameters\n ==========\n\n name : string\n A unique name for the joint.\n parent : Particle or RigidBody\n The parent body of joint.\n child : Particle or RigidBody\n The child body of joint.\n parent_point : Point or Vector, optional\n Attachment point where the joint is fixed to the parent body. If a\n vector is provided, then the attachment point is computed by adding the\n vector to the body's mass center. The default value is the parent's mass\n center.\n child_point : Point or Vector, optional\n Attachment point where the joint is fixed to the child body. If a\n vector is provided, then the attachment point is computed by adding the\n vector to the body's mass center. The default value is the child's mass\n center.\n parent_interframe : ReferenceFrame, optional\n Intermediate frame of the parent body with respect to which the joint\n transformation is formulated. If a Vector is provided then an interframe\n is created which aligns its X axis with the given vector. The default\n value is the parent's own frame.\n child_interframe : ReferenceFrame, optional\n Intermediate frame of the child body with respect to which the joint\n transformation is formulated. If a Vector is provided then an interframe\n is created which aligns its X axis with the given vector. The default\n value is the child's own frame.\n\n Attributes\n ==========\n\n name : string\n The joint's name.\n parent : Particle or RigidBody\n The joint's parent body.\n child : Particle or RigidBody\n The joint's child body.\n coordinates : Matrix\n Matrix of the joint's generalized coordinates. The default value is\n ``dynamicsymbols(f'q_{joint.name}')``.\n speeds : Matrix\n Matrix of the joint's generalized speeds. The default value is\n ``dynamicsymbols(f'u_{joint.name}')``.\n parent_point : Point\n Attachment point where the joint is fixed to the parent body.\n child_point : Point\n Attachment point where the joint is fixed to the child body.\n parent_interframe : ReferenceFrame\n Intermediate frame of the parent body with respect to which the joint\n transformation is formulated.\n child_interframe : ReferenceFrame\n Intermediate frame of the child body with respect to which the joint\n transformation is formulated.\n kdes : Matrix\n Kinematical differential equations of the joint.\n\n Examples\n =========\n\n A single weld joint is created from two bodies and has the following basic\n attributes:\n\n >>> from sympy.physics.mechanics import RigidBody, WeldJoint\n >>> parent = RigidBody('P')\n >>> parent\n P\n >>> child = RigidBody('C')\n >>> child\n C\n >>> joint = WeldJoint('PC', parent, child)\n >>> joint\n WeldJoint: PC parent: P child: C\n >>> joint.name\n 'PC'\n >>> joint.parent\n P\n >>> joint.child\n C\n >>> joint.parent_point\n P_masscenter\n >>> joint.child_point\n C_masscenter\n >>> joint.coordinates\n Matrix(0, 0, [])\n >>> joint.speeds\n Matrix(0, 0, [])\n >>> child.frame.ang_vel_in(parent.frame)\n 0\n >>> child.frame.dcm(parent.frame)\n Matrix([\n [1, 0, 0],\n [0, 1, 0],\n [0, 0, 1]])\n >>> joint.child_point.pos_from(joint.parent_point)\n 0\n\n To further demonstrate the use of the weld joint, two relatively-fixed\n bodies rotated by a quarter turn about the Y axis can be created as follows:\n\n >>> from sympy import symbols, pi\n >>> from sympy.physics.mechanics import ReferenceFrame, RigidBody, WeldJoint\n >>> l1, l2 = symbols('l1 l2')\n\n First create the bodies to represent the parent and rotated child body.\n\n >>> parent = RigidBody('P')\n >>> child = RigidBody('C')\n\n Next the intermediate frame specifying the fixed rotation with respect to\n the parent can be created.\n\n >>> rotated_frame = ReferenceFrame('Pr')\n >>> rotated_frame.orient_axis(parent.frame, parent.y, pi / 2)\n\n The weld between the parent body and child body is located at a distance\n ``l1`` from the parent's center of mass in the X direction and ``l2`` from\n the child's center of mass in the child's negative X direction.\n\n >>> weld = WeldJoint('weld', parent, child, parent_point=l1 * parent.x,\n ... child_point=-l2 * child.x,\n ... parent_interframe=rotated_frame)\n\n Now that the joint has been established, the kinematics of the bodies can be\n accessed. The direction cosine matrix of the child body with respect to the\n parent can be found:\n\n >>> child.frame.dcm(parent.frame)\n Matrix([\n [0, 0, -1],\n [0, 1, 0],\n [1, 0, 0]])\n\n As can also been seen from the direction cosine matrix, the parent X axis is\n aligned with the child's Z axis:\n >>> parent.x == child.z\n True\n\n The position of the child's center of mass with respect to the parent's\n center of mass can be found with:\n\n >>> child.masscenter.pos_from(parent.masscenter)\n l1*P_frame.x + l2*C_frame.x\n\n The angular velocity of the child with respect to the parent is 0 as one\n would expect.\n\n >>> child.frame.ang_vel_in(parent.frame)\n 0", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_01", "repo": "sympy", "question": "What are the default visual properties and display settings for poles and zeros in the pole_zero_plot function of SymPy's control module?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "In the pole_zero_plot function of SymPy's control module, poles are represented by 'x' shaped markers with a default color of blue and a default markersize of 10, while zeros are represented by circular markers with a default color of orange and a default markersize of 7. The plot is rendered on a complex plane. By default, the grid is enabled (True), the coordinate axes are not shown (False), and the plot is displayed immediately (show defaults to True). The function is also known as a PZ Plot or PZ Map.", "rubric": [ "Poles are represented by 'x' shaped markers", "Poles have a default color of blue", "Poles have a default markersize of 10", "Zeros are represented by circular ('o') markers", "Zeros have a default color of orange", "Zeros have a default markersize of 7", "The plot is rendered on a complex plane (Real Axis vs Imaginary Axis)", "Grid is enabled by default (True)", "The show parameter defaults to True (plot is displayed immediately)", "The function is also known as a PZ Plot or PZ Map" ], "key_files": [ "sympy/physics/control/control_plots.py" ], "source_doc": "[docstring: sympy/physics/control/control_plots.py] sympy.physics.control.control_plots.pole_zero_plot\nReturns the Pole-Zero plot (also known as PZ Plot or PZ Map) of a system.\n\n A Pole-Zero plot is a graphical representation of a system's poles and\n zeros. It is plotted on a complex plane, with circular markers representing\n the system's zeros and 'x' shaped markers representing the system's poles.\n\n Parameters\n ==========\n\n system : SISOLinearTimeInvariant type systems\n The system for which the pole-zero plot is to be computed.\n pole_color : str, tuple, optional\n The color of the pole points on the plot. Default color\n is blue. The color can be provided as a matplotlib color string,\n or a 3-tuple of floats each in the 0-1 range.\n pole_markersize : Number, optional\n The size of the markers used to mark the poles in the plot.\n Default pole markersize is 10.\n zero_color : str, tuple, optional\n The color of the zero points on the plot. Default color\n is orange. The color can be provided as a matplotlib color string,\n or a 3-tuple of floats each in the 0-1 range.\n zero_markersize : Number, optional\n The size of the markers used to mark the zeros in the plot.\n Default zero markersize is 7.\n grid : boolean, optional\n If ``True``, the plot will have a grid. Defaults to True.\n show_axes : boolean, optional\n If ``True``, the coordinate axes will be shown. Defaults to False.\n show : boolean, optional\n If ``True``, the plot will be displayed otherwise\n the equivalent matplotlib ``plot`` object will be returned.\n Defaults to True.\n\n Examples\n ========\n\n .. plot::\n :context: close-figs\n :format: doctest\n :include-source: True\n\n >>> from sympy.abc import s\n >>> from sympy.physics.control.lti import TransferFunction\n >>> from sympy.physics.control.control_plots import pole_zero_plot\n >>> tf1 = TransferFunction(s**2 + 1, s**4 + 4*s**3 + 6*s**2 + 5*s + 2, s)\n >>> pole_zero_plot(tf1) # doctest: +SKIP\n\n See Also\n ========\n\n pole_zero_numerical_data\n\n References\n ==========\n\n .. [1] https://en.wikipedia.org/wiki/Pole%E2%80%93zero_plot", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_04", "repo": "sympy", "question": "How does the HadamardGate in the quantum module handle single and multi-qubit applications, and what does the target parameter represent?", "category": "how", "sub_type": "system_design", "gold_answer": "The HadamardGate in SymPy's quantum module applies to a single qubit specified by a 'target' integer parameter. When applied to the |1\u27e9 state, it produces the superposition sqrt(2)*|0>/2 - sqrt(2)*|1>/2 (note the minus sign for the |1\u27e9 component). For multi-qubit systems, multiple HadamardGates can be chained together - for example, applying HadamardGate(0)*HadamardGate(1) to a Bell state (1/sqrt(2))*(|00\u27e9+|11\u27e9) results in sqrt(2)*|00>/2 + sqrt(2)*|11>/2, demonstrating that the Hadamard gates preserve the entanglement structure of the Bell state. The target parameter uses integer indexing where 0 refers to the rightmost (least significant) qubit in the ket notation.", "rubric": [ "HadamardGate takes a single integer 'target' parameter specifying which qubit it acts on", "The target index 0 refers to the rightmost (least significant) qubit in the ket notation", "Applying HadamardGate to |1\u27e9 produces sqrt(2)*|0>/2 - sqrt(2)*|1>/2 (with a minus sign for the |1\u27e9 component)", "Multiple HadamardGates can be chained for multi-qubit systems (e.g., HadamardGate(0)*HadamardGate(1))", "The gate uses a target matrix and applies it by finding the appropriate column based on the qubit's current state and computing a linear combination of resulting qubit states" ], "key_files": [ "sympy/physics/quantum/gate.py" ], "source_doc": "[docstring: sympy/physics/quantum/gate.py] sympy.physics.quantum.gate.HadamardGate\nsympy.physics.quantum.gate.HadamardGate:\n The single qubit Hadamard gate.\n\n Parameters\n ----------\n target : int\n The target qubit this gate will apply to.\n\n Examples\n ========\n\n >>> from sympy import sqrt\n >>> from sympy.physics.quantum.qubit import Qubit\n >>> from sympy.physics.quantum.gate import HadamardGate\n >>> from sympy.physics.quantum.qapply import qapply\n >>> qapply(HadamardGate(0)*Qubit('1'))\n sqrt(2)*|0>/2 - sqrt(2)*|1>/2\n >>> # Hadamard on bell state, applied on 2 qubits.\n >>> psi = 1/sqrt(2)*(Qubit('00')+Qubit('11'))\n >>> qapply(HadamardGate(0)*HadamardGate(1)*psi)\n sqrt(2)*|00>/2 + sqrt(2)*|11>/2", "verification_verdict": "warn", "verification_issues": [ "The claim that 'the target parameter uses integer indexing where 0 refers to the rightmost (least significant) qubit in the ket notation' is not explicitly stated in the documentation, though it is a plausible inference from the examples (HadamardGate(0) applied to Qubit('1') affects the single qubit, and in the 2-qubit example HadamardGate(0) and HadamardGate(1) are used).", "The claim that 'the Hadamard gates preserve the entanglement structure of the Bell state' is an interpretation not explicitly stated in the documentation - the documentation only shows the input and output of the computation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_05", "repo": "sympy", "question": "What is the CNotGate class in the quantum module, and what commutation relations does it define with other gates?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The CNotGate (CNOT) in SymPy's quantum physics module is a two-qubit controlled-NOT gate that performs the NOT (X gate) on the target qubit if the control qubits all have the value 1. It takes a label parameter as a tuple of the form (control, target). An important caveat documented is that qubits are indexed from right to left, so CNOT(1,0) applied to |10> gives |11>. The gate commutes with several other gates under specific conditions: [CNOT(i, j), Z(i)] == 0, [CNOT(i, j), T(i)] == 0, [CNOT(i, j), S(i)] == 0, [CNOT(i, j), X(j)] == 0, and [CNOT(i, j), CNOT(i,k)] == 0. Note that Z, T, and S (Phase) gates commute with CNOT when applied to the control qubit (i), while the X gate commutes when applied to the target qubit (j), and two CNOT gates commute when they share the same control qubit.", "rubric": [ "Identifies CNotGate as a two-qubit controlled-NOT gate that applies X (NOT) on the target qubit when control qubits are 1", "Mentions the label parameter is a tuple of the form (control, target)", "Notes that qubits are indexed from right to left (e.g., CNOT(1,0) on |10> gives |11>)", "States that Z, T, and S (Phase) gates commute with CNOT when applied to the control qubit", "States that X gate commutes with CNOT when applied to the target qubit", "States that two CNOT gates commute when they share the same control qubit" ], "key_files": [ "sympy/physics/quantum/gate.py" ], "source_doc": "[docstring: sympy/physics/quantum/gate.py] sympy.physics.quantum.gate.CNotGate\nsympy.physics.quantum.gate.CNotGate:\n Two qubit controlled-NOT.\n\n This gate performs the NOT or X gate on the target qubit if the control\n qubits all have the value 1.\n\n Parameters\n ----------\n label : tuple\n A tuple of the form (control, target).\n\n Examples\n ========\n\n >>> from sympy.physics.quantum.gate import CNOT\n >>> from sympy.physics.quantum.qapply import qapply\n >>> from sympy.physics.quantum.qubit import Qubit\n >>> c = CNOT(1,0)\n >>> qapply(c*Qubit('10')) # note that qubits are indexed from right to left\n |11>\n\nsympy.physics.quantum.gate.CNotGate._eval_hilbert_space:\n This returns the smallest possible Hilbert space.\n\nsympy.physics.quantum.gate.CNotGate.min_qubits:\n The minimum number of qubits this gate needs to act on.\n\nsympy.physics.quantum.gate.CNotGate.targets:\n A tuple of target qubits.\n\nsympy.physics.quantum.gate.CNotGate.controls:\n A tuple of control qubits.\n\nsympy.physics.quantum.gate.CNotGate.gate:\n The non-controlled gate that will be applied to the targets.\n\nsympy.physics.quantum.gate.CNotGate._eval_commutator_ZGate:\n [CNOT(i, j), Z(i)] == 0.\n\nsympy.physics.quantum.gate.CNotGate._eval_commutator_TGate:\n [CNOT(i, j), T(i)] == 0.\n\nsympy.physics.quantum.gate.CNotGate._eval_commutator_PhaseGate:\n [CNOT(i, j), S(i)] == 0.\n\nsympy.physics.quantum.gate.CNotGate._eval_commutator_XGate:\n [CNOT(i, j), X(j)] == 0.\n\nsympy.physics.quantum.gate.CNotGate._eval_commutator_CNotGate:\n [CNOT(i, j), CNOT(i,k)] == 0.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_07", "repo": "sympy", "question": "Where is OracleGate implemented and how does it flip the sign of matched qubits in Grover's algorithm?", "category": "where", "sub_type": "feature_location", "gold_answer": "The OracleGate in SymPy's quantum module is located in sympy/physics/quantum/grover.py. To use it, you define a callable function (oracle) that returns a boolean on a computational basis, and pass it along with the number of qubits. The gate works by flipping the sign of qubits when the oracle function returns true (i.e., finds the desired qubits). For example, to flip the sign of |2>, you create a lambda like `f = lambda qubits: qubits == IntQubit(2)` and instantiate `OracleGate(2, f)`. When applied via qapply to IntQubit(2), it returns -|2>, and when applied to non-matching qubits like IntQubit(3), it returns |3> unchanged. The gate's _eval_hilbert_space method returns the smallest possible Hilbert space, and it can be represented in the computational basis via _represent_ZGate.", "rubric": [ "Identifies that OracleGate is located in sympy/physics/quantum/grover.py", "Explains that OracleGate takes the number of qubits and a callable oracle function as arguments", "Explains that the oracle function returns true/false on computational basis states", "Explains that _apply_operator_Qubit returns the negative of the qubits (flips sign) when the oracle returns true, and returns them unchanged otherwise", "Mentions _eval_hilbert_space returns ComplexSpace(2)**nqubits (smallest possible Hilbert space)", "Mentions _represent_ZGate builds a matrix representation by flipping diagonal entries to -1 where the oracle returns true" ], "key_files": [ "sympy/physics/quantum/grover.py" ], "source_doc": "[docstring: sympy/physics/quantum/grover.py] sympy.physics.quantum.grover.OracleGate\nsympy.physics.quantum.grover.OracleGate:\n A black box gate.\n\n The gate marks the desired qubits of an unknown function by flipping\n the sign of the qubits. The unknown function returns true when it\n finds its desired qubits and false otherwise.\n\n Parameters\n ==========\n\n qubits : int\n Number of qubits.\n\n oracle : callable\n A callable function that returns a boolean on a computational basis.\n\n Examples\n ========\n\n Apply an Oracle gate that flips the sign of ``|2>`` on different qubits::\n\n >>> from sympy.physics.quantum.qubit import IntQubit\n >>> from sympy.physics.quantum.qapply import qapply\n >>> from sympy.physics.quantum.grover import OracleGate\n >>> f = lambda qubits: qubits == IntQubit(2)\n >>> v = OracleGate(2, f)\n >>> qapply(v*IntQubit(2))\n -|2>\n >>> qapply(v*IntQubit(3))\n |3>\n\nsympy.physics.quantum.grover.OracleGate._eval_hilbert_space:\n This returns the smallest possible Hilbert space.\n\nsympy.physics.quantum.grover.OracleGate.search_function:\n The unknown function that helps find the sought after qubits.\n\nsympy.physics.quantum.grover.OracleGate.targets:\n A tuple of target qubits.\n\nsympy.physics.quantum.grover.OracleGate._apply_operator_Qubit:\n Apply this operator to a Qubit subclass.\n\n Parameters\n ==========\n\n qubits : Qubit\n The qubit subclass to apply this operator to.\n\n Returns\n =======\n\n state : Expr\n The resulting quantum state.\n\nsympy.physics.quantum.grover.OracleGate._represent_ZGate:\n Represent the OracleGate in the computational basis.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_09", "repo": "sympy", "question": "What does the `lr_op` function in the quantum identity search module do, and what does it return?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The `lr_op` function in `sympy/physics/quantum/identitysearch.py` performs a LR operation on gate rule expressions. Specifically, it multiplies both the left and right circuits with the dagger (inverse) of the left circuit's rightmost gate, where the dagger is multiplied on the right side of both circuits. The function takes two gate tuples representing the left and right circuits of a gate rule expression. If a LR operation is possible, it returns a 2-tuple (LHS, RHS) representing the new gate rule with LHS as the left circuit and RHS as the right circuit. If a LR operation is not possible, the function returns None. For example, `lr_op((x, y, z), ())` returns `((X(0), Y(0)), (Z(0),))` because Z(0)'s dagger is multiplied on the right of both circuits - removing Z from the left circuit's right end and adding Z(0) (which is its own dagger for Pauli gates) to the right circuit's right end.", "rubric": [ "Explains that lr_op performs a LR operation on gate rule expressions", "States that it multiplies both left and right circuits with the dagger (inverse) of the left circuit's rightmost gate on the right side", "Mentions that it takes two gate tuples representing left and right circuits of a gate rule expression", "States that it returns a 2-tuple (LHS, RHS) representing the new gate rule if a LR operation is possible", "States that it returns None if a LR operation is not possible", "Explains the effect: the rightmost gate is removed from the left circuit and its dagger is appended to the right circuit" ], "key_files": [ "sympy/physics/quantum/identitysearch.py" ], "source_doc": "[docstring: sympy/physics/quantum/identitysearch.py] sympy.physics.quantum.identitysearch.lr_op\nPerform a LR operation.\n\n A LR operation multiplies both left and right circuits\n with the dagger of the left circuit's rightmost gate, and\n the dagger is multiplied on the right side of both circuits.\n\n If a LR is possible, it returns the new gate rule as a\n 2-tuple (LHS, RHS), where LHS is the left circuit and\n and RHS is the right circuit of the new rule.\n If a LR is not possible, None is returned.\n\n Parameters\n ==========\n\n left : Gate tuple\n The left circuit of a gate rule expression.\n right : Gate tuple\n The right circuit of a gate rule expression.\n\n Examples\n ========\n\n Generate a new gate rule using a LR operation:\n\n >>> from sympy.physics.quantum.identitysearch import lr_op\n >>> from sympy.physics.quantum.gate import X, Y, Z\n >>> x = X(0); y = Y(0); z = Z(0)\n >>> lr_op((x, y, z), ())\n ((X(0), Y(0)), (Z(0),))\n\n >>> lr_op((x, y), (z,))\n ((X(0),), (Z(0), Y(0)))", "verification_verdict": "warn", "verification_issues": [ "The explanation about Z(0) being its own dagger because it's a Pauli gate is not stated in the documentation - it's a plausible extrapolation based on quantum mechanics knowledge but not directly supported by the doc.", "The phrase 'removing Z from the left circuit's right end and adding Z(0) to the right circuit's right end' is an interpretation of the operation that simplifies the documented description of 'multiplying both circuits with the dagger of the left circuit's rightmost gate on the right side'. While consistent with the example output, this specific mechanical description isn't explicitly in the docs." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_06", "repo": "sympy", "question": "Why does the quantum Grover module include a `superposition_basis` function, and what role does it play in the algorithm?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The purpose of the `superposition_basis` function in sympy's quantum grover module is to create an equal superposition of the computational basis states. It takes a number of qubits as input and returns a Qubit state where all computational basis states have equal amplitude. For example, with 2 qubits, it produces the state |0>/2 + |1>/2 + |2>/2 + |3>/2, which represents all 4 possible basis states (2^2 = 4) each with equal coefficient of 1/2. This is a fundamental step in Grover's search algorithm, where the algorithm begins by creating an equal superposition of all possible states before applying the oracle and diffusion operators. The function abstracts the creation of this initial uniform superposition state that serves as the starting point for quantum search.", "rubric": [ "Explains that superposition_basis creates an equal superposition of all computational basis states", "Mentions it takes a number of qubits as input and produces a state with equal amplitudes (1/sqrt(2^n)) for each basis state", "Explains it serves as the initial/starting state for Grover's search algorithm before oracle and diffusion operations are applied", "Notes that the function sums IntQubit states weighted by equal amplitude coefficients" ], "key_files": [ "sympy/physics/quantum/grover.py" ], "source_doc": "[docstring: sympy/physics/quantum/grover.py] sympy.physics.quantum.grover.superposition_basis\nCreates an equal superposition of the computational basis.\n\n Parameters\n ==========\n\n nqubits : int\n The number of qubits.\n\n Returns\n =======\n\n state : Qubit\n An equal superposition of the computational basis with nqubits.\n\n Examples\n ========\n\n Create an equal superposition of 2 qubits::\n\n >>> from sympy.physics.quantum.grover import superposition_basis\n >>> superposition_basis(2)\n |0>/2 + |1>/2 + |2>/2 + |3>/2", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_10", "repo": "sympy", "question": "Why do inner products like `` move to the left of quantum expressions, and why are they prioritized over outer products?", "category": "why", "sub_type": "performance", "gold_answer": "In complex quantum expressions where there is ambiguity about whether inner or outer products should be created, inner products are given high priority. The reason inner products like move to the left of expressions (as shown in the example `k*b*k*b` producing `*|k>>> from sympy.physics.quantum import Bra, Ket\n >>> b = Bra('b')\n >>> k = Ket('k')\n >>> ip = b*k\n >>> ip\n \n >>> ip.bra\n >> ip.ket\n |k>\n\n In quantum expressions, inner products will be automatically\n identified and created::\n\n >>> b*k\n \n\n In more complex expressions, where there is ambiguity in whether inner or\n outer products should be created, inner products have high priority::\n\n >>> k*b*k*b\n *|k> moved to the left of the expression\n because inner products are commutative complex numbers.\n\n References\n ==========\n\n .. [1] https://en.wikipedia.org/wiki/Inner_product", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sympy_gen_08", "repo": "sympy", "question": "How does the ll_op function in the quantum identity search module transform the left and right circuits?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "The LL operation works by taking the dagger (inverse) of the leftmost gate of the left circuit and multiplying it on the left side of both the left and right circuits. Specifically: (1) identify the leftmost gate of the left circuit, (2) compute its dagger, (3) multiply that dagger on the left of both the left circuit and the right circuit. This effectively removes the leftmost gate from the left circuit (since gate * dagger = identity) and prepends the dagger to the right circuit. For example, if left=(X, Y, Z) and right=(), the leftmost gate is X, so X\u2020 is multiplied on the left of both sides, yielding left=(Y, Z) and right=(X\u2020,). Since X is its own inverse (X\u2020 = X for Pauli gates), the result is ((Y(0), Z(0)), (X(0),)). If a LL operation is not possible (e.g., the left circuit is empty), the function returns None rather than raising an error.", "rubric": [ "Explains that ll_op takes the leftmost gate of the left circuit and computes its dagger (inverse)", "States that the dagger is multiplied on the left side of both the left and right circuits", "Explains that this effectively removes the leftmost gate from the left circuit (leaving left[1:])", "States that the dagger of the leftmost gate is prepended to the right circuit", "Mentions that the function returns None if the operation is not possible (e.g., left circuit is empty or gate is not unitary)" ], "key_files": [ "sympy/physics/quantum/identitysearch.py" ], "source_doc": "[docstring: sympy/physics/quantum/identitysearch.py] sympy.physics.quantum.identitysearch.ll_op\nPerform a LL operation.\n\n A LL operation multiplies both left and right circuits\n with the dagger of the left circuit's leftmost gate, and\n the dagger is multiplied on the left side of both circuits.\n\n If a LL is possible, it returns the new gate rule as a\n 2-tuple (LHS, RHS), where LHS is the left circuit and\n and RHS is the right circuit of the new rule.\n If a LL is not possible, None is returned.\n\n Parameters\n ==========\n\n left : Gate tuple\n The left circuit of a gate rule expression.\n right : Gate tuple\n The right circuit of a gate rule expression.\n\n Examples\n ========\n\n Generate a new gate rule using a LL operation:\n\n >>> from sympy.physics.quantum.identitysearch import ll_op\n >>> from sympy.physics.quantum.gate import X, Y, Z\n >>> x = X(0); y = Y(0); z = Z(0)\n >>> ll_op((x, y, z), ())\n ((Y(0), Z(0)), (X(0),))\n\n >>> ll_op((y, z), (x,))\n ((Z(0),), (Y(0), X(0)))", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_03", "repo": "pytest", "question": "Where does deindentation happen in the Source class, and how does it preserve immutability in methods like getstatement?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "When using Source(...) to create a Source object in pytest's internal code module, the source lines are automatically deindented during construction. This means that any indentation present in the original source code fragment is removed when the Source object is created. The Source object is described as immutable, holding a source code fragment. If you need to later deindent an already-created Source object further, you can use the .deindent() method which returns a new Source object (preserving immutability). The .getstatement() method works with line numbers counted from 0, and .getstatementrange() returns a (start, end) tuple spanning the minimal statement region containing a given line number.", "rubric": [ "Explains that deindentation happens automatically during Source object construction (__init__)", "Mentions that .deindent() method returns a new Source object rather than modifying the existing one, preserving immutability", "Notes that .getstatement() uses 0-based line numbers", "Notes that .getstatementrange() returns a (start, end) tuple spanning the minimal statement region containing a given line number", "Identifies the Source class as immutable, holding a source code fragment" ], "key_files": [ "src/_pytest/_code/source.py" ], "source_doc": "[docstring: src/_pytest/_code/source.py] src._pytest._code.source.Source\nsrc._pytest._code.source.Source:\n An immutable object holding a source code fragment.\n\n When using Source(...), the source lines are deindented.\n\nsrc._pytest._code.source.Source.strip:\n Return new Source object with trailing and leading blank lines removed.\n\nsrc._pytest._code.source.Source.indent:\n Return a copy of the source object with all lines indented by the\n given indent-string.\n\nsrc._pytest._code.source.Source.getstatement:\n Return Source statement which contains the given linenumber\n (counted from 0).\n\nsrc._pytest._code.source.Source.getstatementrange:\n Return (start, end) tuple which spans the minimal statement region\n which containing the given lineno.\n\nsrc._pytest._code.source.Source.deindent:\n Return a new Source object deindented.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_02", "repo": "pytest", "question": "Why does `Code.path` return a `str` instead of a `Path` in some cases rather than raising an exception?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The `Code.path` property is designed to return a path object pointing to source code under normal circumstances, but it has a specific fallback behavior: in the case of an `OSError` or when dealing with a non-existing file, it returns a plain `str` instead of a path object. This dual return type design reflects a defensive approach where the code gracefully degrades rather than raising an exception when source files cannot be located on disk. This is a deliberate design choice to handle scenarios where code objects reference files that may have been moved, deleted, or were never on disk (such as code created via `exec` or `compile`). Without the docstring, one would not know that the `str` fallback is specifically tied to `OSError` conditions and non-existing files, as opposed to other potential error conditions.", "rubric": [ "Explains that the str fallback is triggered by OSError or non-existing files", "Mentions it's a defensive/graceful degradation approach to handle missing or unreachable source files", "Notes that code objects may reference files that were moved, deleted, or never existed on disk (e.g., exec/compile)", "Identifies that the return type is explicitly Path | str, with str being the raw co_filename" ], "key_files": [ "src/_pytest/_code/code.py" ], "source_doc": "[docstring: src/_pytest/_code/code.py] src._pytest._code.code.Code\nsrc._pytest._code.code.Code:\n Wrapper around Python code objects.\n\nsrc._pytest._code.code.Code.path:\n Return a path object pointing to source code, or an ``str`` in\n case of ``OSError`` / non-existing file.\n\nsrc._pytest._code.code.Code.fullsource:\n Return a _pytest._code.Source object for the full source file of the code.\n\nsrc._pytest._code.code.Code.source:\n Return a _pytest._code.Source object for the code object's source only.\n\nsrc._pytest._code.code.Code.getargs:\n Return a tuple with the argument names for the code object.\n\n If 'var' is set True also return the names of the variable and\n keyword arguments when present.", "verification_verdict": "warn", "verification_issues": [ "The claim that the str fallback reflects a 'defensive approach where the code gracefully degrades rather than raising an exception' is a plausible extrapolation but not explicitly stated in the documentation.", "The claim about handling 'code created via exec or compile' is an extrapolation not directly supported by the documentation.", "The claim 'This is a deliberate design choice' is an interpretation not explicitly stated in the documentation.", "The statement 'Without the docstring, one would not know that the str fallback is specifically tied to OSError conditions and non-existing files' is editorial commentary, not a factual claim about the code." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_01", "repo": "pytest", "question": "What custom doctest option flags does pytest register, and how does the NUMBER flag compare floating-point values?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The NUMBER option in pytest's doctest support compares floating-point numbers using pytest.approx with a relative tolerance equal to the precision written in the expected output. For example, writing '3.14' means the comparison uses pytest.approx(actual, rel=10**-2), matching to 2 decimal places. Writing '3.1416' would require matching to approximately 4 decimal places. Importantly, NUMBER matches floating-point numbers appearing anywhere in the output, even inside strings, which is why the documentation warns it may not be appropriate to enable globally in the doctest_optionflags configuration. The NUMBER option was added in pytest version 5.1. Additionally, pytest introduces ALLOW_UNICODE (which strips the 'u' prefix from unicode strings to allow doctests to run unchanged in Python 2 and 3) and ALLOW_BYTES (which strips the 'b' prefix from byte strings in expected output).", "rubric": [ "Mentions the three custom flags: ALLOW_UNICODE, ALLOW_BYTES, and NUMBER", "Explains that ALLOW_UNICODE strips the 'u' prefix from unicode string literals for Python 2/3 compatibility", "Explains that ALLOW_BYTES strips the 'b' prefix from byte string literals", "Explains that NUMBER uses pytest.approx (or approximate comparison) with abs=10**-precision where precision is derived from the number of fractional digits in the expected output", "Explains how precision is calculated: the length of the fraction part, adjusted by any exponent", "Notes that NUMBER matches floating-point numbers anywhere in the output (not selectively), since _number_re.finditer is applied to the entire want/got strings" ], "key_files": [ "doc/en/how-to/doctest.rst" ], "source_doc": "[doc_file: doc/en/how-to/doctest.rst] Using 'doctest' options\nPython's standard :mod:`doctest` module provides some :ref:`options `\nto configure the strictness of doctest tests. In pytest, you can enable those flags using the\nconfiguration file.\n\nFor example, to make pytest ignore trailing whitespaces and ignore\nlengthy exception stack traces you can just write:\n\n.. tab:: toml\n\n .. code-block:: toml\n\n [pytest]\n doctest_optionflags = [\"NORMALIZE_WHITESPACE\", \"IGNORE_EXCEPTION_DETAIL\"]\n\n.. tab:: ini\n\n .. code-block:: ini\n\n [pytest]\n doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL\n\nAlternatively, options can be enabled by an inline comment in the doc test\nitself:\n\n.. code-block:: rst\n\n >>> something_that_raises() # doctest: +IGNORE_EXCEPTION_DETAIL\n Traceback (most recent call last):\n ValueError: ...\n\npytest also introduces new options:\n\n* ``ALLOW_UNICODE``: when enabled, the ``u`` prefix is stripped from unicode\n strings in expected doctest output. This allows doctests to run in Python 2\n and Python 3 unchanged.\n\n* ``ALLOW_BYTES``: similarly, the ``b`` prefix is stripped from byte strings\n in expected doctest output.\n\n* ``NUMBER``: when enabled, floating-point numbers only need to match as far as\n the precision you have written in the expected doctest output. The numbers are\n compared using :func:`pytest.approx` with relative tolerance equal to the\n precision. For example, the following output would only need to match to 2\n decimal places when comparing ``3.14`` to\n ``pytest.approx(math.pi, rel=10**-2)``::\n\n >>> math.pi\n 3.14\n\n If you wrote ``3.1416`` then the actual output would need to match to\n approximately 4 decimal places; and so on.\n\n This avoids false positives caused by limited floating-point precision, like\n this::\n\n Expected:\n 0.233\n Got:\n 0.23300000000000001\n\n ``NUMBER`` also supports lists of floating-point numbers -- in fact, it\n matches floating-point numbers appearing anywhere in the output, even inside\n a string! This means that it may not be appropriate to enable globally in\n ``doctest_optionflags`` in your configuration file.\n\n .. versionadded:: 5.1", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_04", "repo": "pytest", "question": "How does the pytest 2.1.2 release address the assertion rewriting issues and platform compatibility problems?", "category": "how", "sub_type": "system_design", "gold_answer": "The bug fixes in pytest 2.1.2 primarily address remaining issues with the 'perfected assertions' feature that was introduced in the 2.1 series. Benjamin Peterson helped fix these assertion-related bugs alongside the bug reporters. Additionally, the release improved compatibility with Jython-2.5.1 and Jython trunk. Users could upgrade by running either 'pip install -U pytest' or 'easy_install -U pytest'.", "rubric": [ "Mentions that bugs relate to the 'perfected assertions' feature introduced in the 2.1 series", "Credits Benjamin Peterson for helping fix assertion-related bugs", "Notes improved compatibility with Jython-2.5.1 and/or Jython trunk", "Mentions that assertion rewriting is not attempted on Jython (uses reinterp instead)", "References upgrade commands: pip install -U pytest or easy_install -U pytest", "Mentions specific fixes like assertion rewriting on files with Windows newlines, boolean operations (issue69), packages (issue68), or different caches with -O option (issue66)" ], "key_files": [ "doc/en/announce/release-2.1.2.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.1.2.rst] py.test 2.1.2: bug fixes and fixes for jython\npytest-2.1.2 is a minor backward compatible maintenance release of the\npopular py.test testing tool. pytest is commonly used for unit,\nfunctional- and integration testing. See extensive docs with examples\nhere:\n\n http://pytest.org/\n\nMost bug fixes address remaining issues with the perfected assertions\nintroduced in the 2.1 series - many thanks to the bug reporters and to Benjamin\nPeterson for helping to fix them. pytest should also work better with\nJython-2.5.1 (and Jython trunk).\n\nIf you want to install or upgrade pytest, just type one of::\n\n pip install -U pytest # or\n easy_install -U pytest\n\nbest,\nholger krekel / https://merlinux.eu/", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_07", "repo": "pytest", "question": "Where does pytest handle the integration between mock.patch decorated functions and fixture argument resolution?", "category": "where", "sub_type": "feature_location", "gold_answer": "To use mock.patch with pytest's fixtures (issue 217), you need either mock-1.0.1 or the Python 3.3 builtin unittest.mock module. This integration point is documented in the pytest 2.3.3 release notes. Additionally, for retrieving option values consistently, the documentation recommends using the newly added `config.getoption(name)` helper function, which was introduced alongside improved documentation for `pytest_addoption()` (issue 127).", "rubric": [ "The num_mock_patch_args function in compat.py counts mock arguments by checking the 'patchings' attribute and comparing against mock.DEFAULT / unittest.mock.DEFAULT sentinels", "getfuncargnames in compat.py strips mock patch arguments from the argument list using num_mock_patch_args so fixtures are resolved correctly", "The code supports both the PyPI 'mock' package and Python's builtin unittest.mock module by checking both sys.modules entries", "config.getoption(name) is the recommended helper for retrieving command line option values, documented in pytest_addoption's hookspec", "The getvalue and getvalueorskip methods are deprecated in favor of getoption" ], "key_files": [ "doc/en/announce/release-2.3.3.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.3.3.rst] Changes between 2.3.2 and 2.3.3\n- fix issue214 - parse modules that contain special objects like e. g.\n flask's request object which blows up on getattr access if no request\n is active. thanks Thomas Waldmann.\n\n- fix issue213 - allow to parametrize with values like numpy arrays that\n do not support an __eq__ operator\n\n- fix issue215 - split test_python.org into multiple files\n\n- fix issue148 - @unittest.skip on classes is now recognized and avoids\n calling setUpClass/tearDownClass, thanks Pavel Repin\n\n- fix issue209 - reintroduce python2.4 support by depending on newer\n pylib which re-introduced statement-finding for pre-AST interpreters\n\n- nose support: only call setup if it's a callable, thanks Andrew\n Taumoefolau\n\n- fix issue219 - add py2.4-3.3 classifiers to TROVE list\n\n- in tracebacks *,** arg values are now shown next to normal arguments\n (thanks Manuel Jacob)\n\n- fix issue217 - support mock.patch with pytest's fixtures - note that\n you need either mock-1.0.1 or the python3.3 builtin unittest.mock.\n\n- fix issue127 - improve documentation for pytest_addoption() and\n add a ``config.getoption(name)`` helper function for consistency.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_05", "repo": "pytest", "question": "What are the key design decisions in how pytest handles the interaction between skip and xfail markers, and how do keywords and the fixture decorator fit into the framework?", "category": "what", "sub_type": "concept_definition", "gold_answer": "In pytest 2.3.0, when a test is both marked with xfail and also skipped (either via a skip-mark or an imperative pytest.skip call), the skip takes precedence over the xfail marker. The rationale for this design decision is that pytest cannot determine the xfail/xpass status of a test when it is skipped - since the test never actually runs, there's no way to know whether it would have passed (xpass) or failed (xfail). Additionally, keywords (request.keywords and node.keywords) are defined as dictionaries containing markers and other info, and they were made writable in this release so that all descendant collection nodes will see keyword values. The @pytest.fixture decorator was introduced to allow direct scoping and parametrization of funcarg factories, while @pytest.setup was introduced as a new marker to allow writing setup functions that accept funcargs.", "rubric": [ "Explains that skip takes precedence over xfail: in pytest_runtest_setup, evaluate_skip_marks is called first and raises a skip.Exception before xfail is evaluated", "Explains the rationale that when a test is skipped, pytest cannot determine xfail/xpass status because the test never runs", "Describes NodeKeywords as a MutableMapping/dictionary-like structure containing markers and info, with parent traversal for lookups (descendant nodes see parent keywords)", "Notes that NodeKeywords supports __setitem__ (writable) so keyword values can be set and propagated to descendant collection nodes", "Mentions that @pytest.fixture (FixtureFunctionMarker) allows direct scoping and parametrization of fixture factories via scope, params, autouse, ids, and name parameters" ], "key_files": [ "doc/en/announce/release-2.3.0.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.3.0.rst] Changes between 2.2.4 and 2.3.0\n- fix issue202 - better automatic names for parametrized test functions\n- fix issue139 - introduce @pytest.fixture which allows direct scoping\n and parametrization of funcarg factories. Introduce new @pytest.setup\n marker to allow the writing of setup functions which accept funcargs.\n- fix issue198 - conftest fixtures were not found on windows32 in some\n circumstances with nested directory structures due to path manipulation issues\n- fix issue193 skip test functions with were parametrized with empty\n parameter sets\n- fix python3.3 compat, mostly reporting bits that previously depended\n on dict ordering\n- introduce re-ordering of tests by resource and parametrization setup\n which takes precedence to the usual file-ordering\n- fix issue185 monkeypatching time.time does not cause pytest to fail\n- fix issue172 duplicate call of pytest.setup-decoratored setup_module\n functions\n- fix junitxml=path construction so that if tests change the\n current working directory and the path is a relative path\n it is constructed correctly from the original current working dir.\n- fix \"python setup.py test\" example to cause a proper \"errno\" return\n- fix issue165 - fix broken doc links and mention stackoverflow for FAQ\n- catch unicode-issues when writing failure representations\n to terminal to prevent the whole session from crashing\n- fix xfail/skip confusion: a skip-mark or an imperative pytest.skip\n will now take precedence before xfail-markers because we\n can't determine xfail/xpass status in case of a skip. see also:\n http://stackoverflow.com/questions/11105828/in-py-test-when-i-explicitly-skip-a-test-that-is-marked-as-xfail-how-can-i-get\n\n- always report installed 3rd party plugins in the header of a test run\n\n- fix issue160: a failing setup of an xfail-marked tests should\n be reported as xfail (not xpass)\n\n- fix issue128: show captured output when capsys/capfd are used\n\n- fix issue179: properly show the dependency chain of factories\n\n- pluginmanager.register(...) now raises ValueError if the\n plugin has been already registered or the name is taken\n\n- fix issue159: improve https://docs.pytest.org/en/6.0.1/faq.html\n especially with respect to the \"magic\" history, also mention\n pytest-django, trial and unittest integration.\n\n- make request.keywords and node.keywords writable. All descendant\n collection nodes will see keyword values. Keywords are dictionaries\n containing markers and other info.\n\n- fix issue 178: xml binary escapes are now wrapped in py.xml.raw\n\n- fix issue 176: correctly catch the builtin AssertionError\n even when we replaced AssertionError with a subclass on the\n python level\n\n- factory discovery no longer fails with magic global callables\n that provide no sane __code__ object (mock.call for example)\n\n- fix issue 182: testdir.inprocess_run now considers passed plugins\n\n- fix issue 188: ensure sys.exc_info is clear on python2\n before calling into a test\n\n- fix issue 191: add unittest TestCase runTest method support\n- fix issue 156: monkeypatch correctly handles class level descriptors\n\n- reporting refinements:\n\n - pytest_report_header now receives a \"startdir\" so that\n you can use startdir.bestrelpath(yourpath) to show\n nice relative path\n\n - allow plugins to implement both pytest_report_header and\n pytest_sessionstart (sessionstart is invoked first).\n\n - don't show deselected reason line if there is none\n\n - py.test -vv will show all of assert comparisons instead of truncating", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_06", "repo": "pytest", "question": "Why did pytest 2.3.2 upgrade to a new version of the py library to fix issue208 and issue29?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The fix for issue208 and issue29 in pytest 2.3.2 involved using a new version of the 'py' library specifically to avoid long pauses when printing tracebacks in long modules. The root cause was a performance problem in traceback rendering: when modules were lengthy, the previous implementation would cause extended delays during traceback output. By upgrading to a newer version of the 'py' library (which pytest depends on for low-level utilities including traceback formatting), these long pauses were eliminated. This is a performance-motivated dependency upgrade rather than a functional bug fix \u2014 the tracebacks were presumably correct but unacceptably slow to produce in certain scenarios involving large source files.", "rubric": [ "Mentions that the fix addressed long pauses/delays when printing tracebacks", "Identifies that the problem occurred specifically with long/large modules", "Explains this was a performance issue in traceback rendering rather than a functional correctness bug", "Notes that the solution was upgrading/depending on a newer version of the py library" ], "key_files": [ "doc/en/announce/release-2.3.2.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.3.2.rst] Changes between 2.3.1 and 2.3.2\n- fix issue208 and fix issue29 use new py version to avoid long pauses\n when printing tracebacks in long modules\n\n- fix issue205 - conftests in subdirs customizing\n pytest_pycollect_makemodule and pytest_pycollect_makeitem\n now work properly\n\n- fix teardown-ordering for parametrized setups\n\n- fix issue127 - better documentation for pytest_addoption\n and related objects.\n\n- fix unittest behaviour: TestCase.runtest only called if there are\n test methods defined\n\n- improve trial support: don't collect its empty\n unittest.TestCase.runTest() method\n\n- \"python setup.py test\" now works with pytest itself\n\n- fix/improve internal/packaging related bits:\n\n - exception message check of test_nose.py now passes on python33 as well\n\n - issue206 - fix test_assertrewrite.py to work when a global\n PYTHONDONTWRITEBYTECODE=1 is present\n\n - add tox.ini to pytest distribution so that ignore-dirs and others config\n bits are properly distributed for maintainers who run pytest-own tests", "verification_verdict": "warn", "verification_issues": [ "The answer states the fix involved 'upgrading to a newer version of the py library' \u2014 the documentation says 'use new py version' which supports this, but the answer's elaboration about 'low-level utilities including traceback formatting' is an extrapolation not explicitly stated in the docs.", "The claim that 'tracebacks were presumably correct but unacceptably slow to produce' is a reasonable inference but not explicitly stated in the documentation.", "The characterization as 'a performance-motivated dependency upgrade rather than a functional bug fix' is a plausible extrapolation but not explicitly confirmed by the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_09", "repo": "pytest", "question": "What new plugins and compatibility details are mentioned in the pytest-2.3.5 release announcement?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The pytest-2.3.5 release announcement mentions four new plugins that emerged around that time: pytest-instafail (show failure information while tests are running), pytest-qt (testing of GUI applications written with QT/Pyside), pytest-xprocess (managing external processes across test runs), and pytest-random (randomize test ordering). The release is described as a maintenance release with no backward compatibility issues foreseen, and all plugins which worked with the prior version are expected to work unmodified. Particular thanks were given to Floris, Ronny, Benjamin and the many bug reporters and fix providers.", "rubric": [ "Mentions pytest-instafail (show failure information while tests are running)", "Mentions pytest-qt (testing of GUI applications written with QT/Pyside)", "Mentions pytest-xprocess (managing external processes across test runs)", "Mentions pytest-random (randomize test ordering)", "Notes it is a maintenance release with no backward compatibility issues foreseen", "States all plugins which worked with the prior version are expected to work unmodified", "Mentions particular thanks to Floris, Ronny, Benjamin and bug reporters/fix providers" ], "key_files": [ "doc/en/announce/release-2.3.5.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.3.5.rst] pytest-2.3.5: bug fixes and little improvements\npytest-2.3.5 is a maintenance release with many bug fixes and little\nimprovements. See the changelog below for details. No backward\ncompatibility issues are foreseen and all plugins which worked with the\nprior version are expected to work unmodified. Speaking of which, a\nfew interesting new plugins saw the light last month:\n\n- pytest-instafail: show failure information while tests are running\n- pytest-qt: testing of GUI applications written with QT/Pyside\n- pytest-xprocess: managing external processes across test runs\n- pytest-random: randomize test ordering\n\nAnd several others like pytest-django saw maintenance releases.\nFor a more complete list, check out\nhttps://pypi.org/search/?q=pytest\n\nFor general information see:\n\n http://pytest.org/\n\nTo install or upgrade pytest:\n\n pip install -U pytest # or\n easy_install -U pytest\n\nParticular thanks to Floris, Ronny, Benjamin and the many bug reporters\nand fix providers.\n\nmay the fixtures be with you,\nholger krekel", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_08", "repo": "pytest", "question": "How does the `-k` keyword expression matching work end-to-end, from parsing the expression to deciding whether a test item matches?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "In pytest 2.3.4, the `-k` option was changed to accept expressions using the same syntax as `-m`, supporting boolean operators like `or` and `and`. This introduced a usage incompatibility: the previous special syntax `TestClass.test_method` (using dot notation) no longer works for selecting a specific method in a specific class. Instead, users must rewrite it as `-k \"TestClass and test_method\"` to achieve the same matching behavior. This means the `-k` expression is now evaluated as a boolean expression where each term is matched against the test's name, and combining terms with `and` ensures both the class name and the method name must be present in the test's identifier for it to be selected. Additionally, yielded test functions gained autouse-fixture support in this release but explicitly cannot accept fixtures as funcargs; the recommended migration path is to use the post-2.0 parametrize features instead of yield-based tests. The release also fixed LIFO ordering for fixture teardowns (issue226) and resolved an autouse discovery bug where autouse-fixtures defined in `a/conftest.py` would not be discovered by tests located in `a/tests/test_some.py`.", "rubric": [ "The expression string is compiled via Expression.compile which uses a Scanner to tokenize and a recursive descent parser to produce a Python AST with boolean operators (and/or/not)", "Identifiers in the expression are prefixed with '$' (IDENT_PREFIX) to handle Python reserved words and are converted to ast.Name nodes", "The compiled AST code is evaluated using eval() with a MatcherAdapter as the locals mapping, which intercepts name lookups and delegates to the matcher", "KeywordMatcher.from_item collects names from the item's parent chain (excluding Session and root Directory), extra keywords, function __dict__ attributes, and marker names", "KeywordMatcher.__call__ performs a case-insensitive substring check of the expression term against any of the collected names", "To select a specific class and method, users must use 'TestClass and test_method' since each identifier is independently matched as a substring against the collected node names" ], "key_files": [ "doc/en/announce/release-2.3.4.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.3.4.rst] pytest-2.3.4: stabilization, more flexible selection via \"-k expr\"\npytest-2.3.4 is a small stabilization release of the py.test tool\nwhich offers uebersimple assertions, scalable fixture mechanisms\nand deep customization for testing with Python. This release\ncomes with the following fixes and features:\n\n- make \"-k\" option accept an expressions the same as with \"-m\" so that one\n can write: -k \"name1 or name2\" etc. This is a slight usage incompatibility\n if you used special syntax like \"TestClass.test_method\" which you now\n need to write as -k \"TestClass and test_method\" to match a certain\n method in a certain test class.\n- allow to dynamically define markers via\n item.keywords[...]=assignment integrating with \"-m\" option\n- yielded test functions will now have autouse-fixtures active but\n cannot accept fixtures as funcargs - it's anyway recommended to\n rather use the post-2.0 parametrize features instead of yield, see:\n http://pytest.org/en/stable/example/how-to/parametrize.html\n- fix autouse-issue where autouse-fixtures would not be discovered\n if defined in an a/conftest.py file and tests in a/tests/test_some.py\n- fix issue226 - LIFO ordering for fixture teardowns\n- fix issue224 - invocations with >256 char arguments now work\n- fix issue91 - add/discuss package/directory level setups in example\n- fixes related to autouse discovery and calling\n\nThanks in particular to Thomas Waldmann for spotting and reporting issues.\n\nSee\n\n http://pytest.org/\n\nfor general information. To install or upgrade pytest:\n\n pip install -U pytest # or\n easy_install -U pytest\n\nbest,\nholger krekel", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pytest_gen_10", "repo": "pytest", "question": "Why does `runtestprotocol` set `item._request` to False and `item.funcargs` to None after teardown completes?", "category": "why", "sub_type": "performance", "gold_answer": "The change to allow re-running of test items in pytest 2.3.5 was motivated by two performance/resource-related goals: (1) it helped fix the pytest-reruntests plugin, and (2) it helped keep fewer fixture/resource references alive. This means the design decision was partly driven by memory/resource management concerns - by allowing test items to be re-run, the framework could release fixture and resource references more aggressively, reducing memory pressure during test runs. This is a performance optimization that reduces the lifetime of objects held in memory during test execution.", "rubric": [ "Mentions that it allows fixture/resource references to be released or garbage collected (memory/resource management)", "Mentions that it enables re-running of test items (e.g., by pytest-rerunfailures or similar plugins)", "Explains that setting _request to False signals a re-run scenario, triggering _initrequest() on subsequent runs to reinitialize fixtures" ], "key_files": [ "doc/en/announce/release-2.3.5.rst" ], "source_doc": "[doc_file: doc/en/announce/release-2.3.5.rst] Changes between 2.3.4 and 2.3.5\n- never consider a fixture function for test function collection\n\n- allow re-running of test items / helps to fix pytest-reruntests plugin\n and also help to keep less fixture/resource references alive\n\n- put captured stdout/stderr into junitxml output even for passing tests\n (thanks Adam Goucher)\n\n- Issue 265 - integrate nose setup/teardown with setupstate\n so it doesn't try to teardown if it did not setup\n\n- issue 271 - don't write junitxml on worker nodes\n\n- Issue 274 - don't try to show full doctest example\n when doctest does not know the example location\n\n- issue 280 - disable assertion rewriting on buggy CPython 2.6.0\n\n- inject \"getfixture()\" helper to retrieve fixtures from doctests,\n thanks Andreas Zeidler\n\n- issue 259 - when assertion rewriting, be consistent with the default\n source encoding of ASCII on Python 2\n\n- issue 251 - report a skip instead of ignoring classes with init\n\n- issue250 unicode/str mixes in parametrization names and values now works\n\n- issue257, assertion-triggered compilation of source ending in a\n comment line doesn't blow up in python2.5 (fixed through py>=1.4.13.dev6)\n\n- fix --genscript option to generate standalone scripts that also\n work with python3.3 (importer ordering)\n\n- issue171 - in assertion rewriting, show the repr of some\n global variables\n\n- fix option help for \"-k\"\n\n- move long description of distribution into README.rst\n\n- improve docstring for metafunc.parametrize()\n\n- fix bug where using capsys with pytest.set_trace() in a test\n function would break when looking at capsys.readouterr()\n\n- allow to specify prefixes starting with \"_\" when\n customizing python_functions test discovery. (thanks Graham Horler)\n\n- improve PYTEST_DEBUG tracing output by putting\n extra data on a new lines with additional indent\n\n- ensure OutcomeExceptions like skip/fail have initialized exception attributes\n\n- issue 260 - don't use nose special setup on plain unittest cases\n\n- fix issue134 - print the collect errors that prevent running specified test items\n\n- fix issue266 - accept unicode in MarkEvaluator expressions", "verification_verdict": "warn", "verification_issues": [ "The answer extrapolates beyond what the documentation states by claiming this was a 'performance optimization that reduces the lifetime of objects held in memory during test execution' and that 'the framework could release fixture and resource references more aggressively, reducing memory pressure during test runs.' The documentation only says it helps 'keep less fixture/resource references alive' without explicitly framing it as a memory pressure or performance optimization.", "The documentation says 'pytest-reruntests' but the answer says 'pytest-reruntests plugin' which matches.", "The two stated goals (fixing pytest-reruntests plugin and keeping fewer fixture/resource references alive) are correctly identified from the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_01", "repo": "astropy", "question": "What does the `ParametersAttribute` descriptor return differently when accessed from the Cosmology class versus from an instance?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The `ParametersAttribute` descriptor in astropy's cosmology module behaves differently depending on whether it is accessed from the class or from an instance. When accessed from the `Cosmology` class itself, it returns a mapping of the `Parameter` objects themselves (e.g., `FlatLambdaCDM.parameters` yields `mappingproxy({'H0': Parameter(...), ...})`). When accessed from a cosmology instance, it returns a mapping of the *values* of those Parameters (e.g., `Planck18.parameters` yields `mappingproxy({'H0': , ...})`). The mapping returned is immutable. This class is specifically used to implement the `astropy.cosmology.Cosmology.parameters` attribute. The `attr_name` parameter specifies the name of a class attribute that is a `MappingProxyType[str, Parameter]` of all the cosmology's parameters.", "rubric": [ "Explains that when accessed from the class, it returns a mapping of Parameter objects themselves", "Explains that when accessed from an instance, it returns a mapping of the parameter values (via getattr on the instance)", "Mentions that the returned mapping is immutable (MappingProxyType)", "Notes that this descriptor implements the Cosmology.parameters attribute", "Mentions that attr_name specifies the class attribute holding the MappingProxyType[str, Parameter] of all the cosmology's parameters" ], "key_files": [ "astropy/cosmology/_src/parameter/descriptors.py" ], "source_doc": "[docstring: astropy/cosmology/_src/parameter/descriptors.py] astropy.cosmology._src.parameter.descriptors.ParametersAttribute\nastropy.cosmology._src.parameter.descriptors.ParametersAttribute:\n Immutable mapping of the :class:`~astropy.cosmology.Parameter` objects or values.\n\n If accessed from the :class:`~astropy.cosmology.Cosmology` class, this returns a\n mapping of the :class:`~astropy.cosmology.Parameter` objects themselves. If\n accessed from an instance, this returns a mapping of the values of the Parameters.\n\n This class is used to implement :obj:`astropy.cosmology.Cosmology.parameters`.\n\n Parameters\n ----------\n attr_name : str\n The name of the class attribute that is a `~types.MappingProxyType[str,\n astropy.cosmology.Parameter]` of all the cosmology's parameters. When accessed\n from the class, this attribute is returned. When accessed from an instance, a\n mapping of the cosmology instance's values for each key is returned.\n\n Examples\n --------\n The normal usage of this class is the ``parameters`` attribute of\n :class:`~astropy.cosmology.Cosmology`.\n\n >>> from astropy.cosmology import FlatLambdaCDM, Planck18\n\n >>> FlatLambdaCDM.parameters\n mappingproxy({'H0': Parameter(...), ...})\n\n >>> Planck18.parameters\n mappingproxy({'H0': , ...})", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_03", "repo": "astropy", "question": "Where can users find help on available readers and supported formats for NDData-derived classes like CCDData?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "To get help on available readers and supported formats for NDData-derived classes like CCDData, users should use the `help()` method on the read attribute. Specifically, `CCDData.read.help()` provides general help on reading CCDData and lists supported formats, `CCDData.read.help('fits')` provides detailed help on a specific format reader (e.g., FITS), and `CCDData.read.list_formats()` prints a list of available formats. This interface is part of the astropy unified I/O layer, and further documentation is available at https://docs.astropy.org/en/stable/nddata and https://docs.astropy.org/en/stable/io/unified.html.", "rubric": [ "Mentions using the help() method on the read attribute (e.g., CCDData.read.help())", "Mentions CCDData.read.help('fits') for getting detailed help on a specific format reader", "Mentions CCDData.read.list_formats() for listing available formats", "Notes this is part of the astropy unified I/O layer (NDIOMixin / NDDataRead class)", "References the documentation URLs (docs.astropy.org/en/stable/nddata and/or io/unified.html)" ], "key_files": [ "astropy/nddata/mixins/ndio.py" ], "source_doc": "[docstring: astropy/nddata/mixins/ndio.py] astropy.nddata.mixins.ndio.NDDataRead\nastropy.nddata.mixins.ndio.NDDataRead:\n Read and parse gridded N-dimensional data and return as an NDData-derived\n object.\n\n This function provides the NDDataBase interface to the astropy unified I/O\n layer. This allows easily reading a file in the supported data formats,\n for example::\n\n >>> from astropy.nddata import CCDData\n >>> dat = CCDData.read('image.fits')\n\n Get help on the available readers for ``CCDData`` using the``help()`` method::\n\n >>> CCDData.read.help() # Get help reading CCDData and list supported formats\n >>> CCDData.read.help('fits') # Get detailed help on CCDData FITS reader\n >>> CCDData.read.list_formats() # Print list of available formats\n\n For more information see:\n\n - https://docs.astropy.org/en/stable/nddata\n - https://docs.astropy.org/en/stable/io/unified.html\n\n Parameters\n ----------\n *args : tuple, optional\n Positional arguments passed through to data reader. If supplied the\n first argument is the input filename.\n format : str, optional\n File format specifier.\n cache : bool, optional\n Caching behavior if file is a URL.\n **kwargs : dict, optional\n Keyword arguments passed through to data reader.\n\n Returns\n -------\n out : `NDData` subclass\n NDData-basd object corresponding to file contents\n\n Notes\n -----", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_04", "repo": "astropy", "question": "How does NDSlicingMixin handle slicing of an NDData object's various attributes when __getitem__ is called?", "category": "how", "sub_type": "system_design", "gold_answer": "When NDSlicingMixin slices an object, the attributes `data`, `mask`, `uncertainty`, and `wcs` are sliced (if set and sliceable), while `unit` and `meta` are left untouched (not sliced). The return is a reference and not a copy, when possible. This means that modifying data values in the sliced result will also change the values in the original object. The internal `_slice` method delegates uncertainty, mask, and wcs to their respective `_slice_*` methods, while data is sliced directly. The `_slice` method returns a dictionary of sliced attributes that is ready to be passed to `self.__class__.__init__(**kwargs)` in the `__getitem__` method.", "rubric": [ "Mentions that data, mask, uncertainty, and wcs are sliced (if set and sliceable)", "Mentions that unit and meta are passed through unchanged (not sliced)", "Mentions that the return is a reference, not a copy, when possible (modifying sliced data affects original)", "Explains that _slice delegates uncertainty, mask, and wcs to their respective _slice_* helper methods while data is sliced directly", "Explains that _slice returns a kwargs dict which __getitem__ passes to self.__class__(**kwargs) to construct a new instance" ], "key_files": [ "astropy/nddata/mixins/ndslicing.py" ], "source_doc": "[docstring: astropy/nddata/mixins/ndslicing.py] astropy.nddata.mixins.ndslicing.NDSlicingMixin\nastropy.nddata.mixins.ndslicing.NDSlicingMixin:\n Mixin to provide slicing on objects using the `NDData`\n interface.\n\n The ``data``, ``mask``, ``uncertainty`` and ``wcs`` will be sliced, if\n set and sliceable. The ``unit`` and ``meta`` will be untouched. The return\n will be a reference and not a copy, if possible.\n\n Examples\n --------\n Using this Mixin with `~astropy.nddata.NDData`:\n\n >>> from astropy.nddata import NDData, NDSlicingMixin\n >>> class NDDataSliceable(NDSlicingMixin, NDData):\n ... pass\n\n Slicing an instance containing data::\n\n >>> nd = NDDataSliceable([1,2,3,4,5])\n >>> nd[1:3]\n NDDataSliceable([2, 3])\n\n Also the other attributes are sliced for example the ``mask``::\n\n >>> import numpy as np\n >>> mask = np.array([True, False, True, True, False])\n >>> nd2 = NDDataSliceable(nd, mask=mask)\n >>> nd2slc = nd2[1:3]\n >>> nd2slc[nd2slc.mask]\n NDDataSliceable([\u2014])\n\n Be aware that changing values of the sliced instance will change the values\n of the original::\n\n >>> nd3 = nd2[1:3]\n >>> nd3.data[0] = 100\n >>> nd2\n NDDataSliceable([\u2014\u2014\u2014, 100, \u2014\u2014\u2014, \u2014\u2014\u2014, 5])\n\n See Also\n --------\n NDDataRef\n NDDataArray\n\nastropy.nddata.mixins.ndslicing.NDSlicingMixin._slice:\n Collects the sliced attributes and passes them back as `dict`.\n\n It passes uncertainty, mask and wcs to their appropriate ``_slice_*``\n method, while ``meta`` and ``unit`` are simply taken from the original.\n The data is assumed to be sliceable and is sliced directly.\n\n When possible the return should *not* be a copy of the data but a\n reference.\n\n Parameters\n ----------\n item : slice\n The slice passed to ``__getitem__``.\n\n Returns\n -------\n dict :\n Containing all the attributes after slicing - ready to\n use them to create ``self.__class__.__init__(**kwargs)`` in\n ``__getitem__``.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_02", "repo": "astropy", "question": "Why can't you use Table.read() to access a reader registered with a separate UnifiedInputRegistry instance?", "category": "why", "sub_type": "design_rationale", "gold_answer": "When you create a separate UnifiedInputRegistry and register a reader with it, you cannot use the class-level convenience method (e.g., Table.read()) to access that reader. This is because Table.read uses Astropy's default global registry, not the custom separate registry you created. Instead, you must call the read method directly on the registry instance itself (e.g., read_reg.read(Table, 'my_table_file.mtf', format='my-table-format')). The design rationale is that UnifiedInputRegistry is intentionally a separate, isolated read-only registry that does not interfere with or connect to the global default registry that class methods like Table.read are wired to use.", "rubric": [ "Explains that Table.read() uses the default global registry (default_registry), not a custom/separate registry instance", "Mentions that UnifiedInputRegistry is designed as an isolated registry that does not connect to the global default registry", "States that to use a reader from a separate registry, you must call the read method directly on the registry instance (e.g., read_reg.read(Table, ...))" ], "key_files": [ "astropy/io/registry/core.py" ], "source_doc": "[docstring: astropy/io/registry/core.py] astropy.io.registry.core.UnifiedInputRegistry\nastropy.io.registry.core.UnifiedInputRegistry:\n Read-only Unified Registry.\n\n .. versionadded:: 5.0\n\n Examples\n --------\n First let's start by creating a read-only registry.\n\n .. code-block:: python\n\n >>> from astropy.io.registry import UnifiedInputRegistry\n >>> read_reg = UnifiedInputRegistry()\n\n There is nothing in this registry. Let's make a reader for the\n :class:`~astropy.table.Table` class::\n\n from astropy.table import Table\n\n def my_table_reader(filename, some_option=1):\n # Read in the table by any means necessary\n return table # should be an instance of Table\n\n Such a function can then be registered with the I/O registry::\n\n read_reg.register_reader('my-table-format', Table, my_table_reader)\n\n Note that we CANNOT then read in a table with::\n\n d = Table.read('my_table_file.mtf', format='my-table-format')\n\n Why? because ``Table.read`` uses Astropy's default global registry and this\n is a separate registry.\n Instead we can read by the read method on the registry::\n\n d = read_reg.read(Table, 'my_table_file.mtf', format='my-table-format')\n\nastropy.io.registry.core.UnifiedInputRegistry.register_reader:\n Register a reader function.\n\n Parameters\n ----------\n data_format : str\n The data format identifier. This is the string that will be used to\n specify the data type when reading.\n data_class : class\n The class of the object that the reader produces.\n function : function\n The function to read in a data object.\n force : bool, optional\n Whether to override any existing function if already present.\n Default is ``False``.\n priority : int, optional\n The priority of the reader, used to compare possible formats when\n trying to determine the best reader to use. Higher priorities are\n preferred over lower priorities, with the default priority being 0\n (negative numbers are allowed though).\n\nastropy.io.registry.core.UnifiedInputRegistry.unregister_reader:\n Unregister a reader function.\n\n Parameters\n ----------\n data_format : str\n The data format identifier.\n data_class : class\n The class of the object that the reader produces.\n\nastropy.io.registry.core.UnifiedInputRegistry.get_reader:\n Get reader for ``data_format``.\n\n Parameters\n ----------\n data_format : str\n The data format identifier. This is the string that is used to\n specify the data type when reading/writing.\n data_class : class\n The class of the object that can be written.\n\n Returns\n -------\n reader : callable\n The registered reader function for this format and class.\n\nastropy.io.registry.core.UnifiedInputRegistry.read:\n Read in data.\n\n Parameters\n ----------\n cls : class\n *args\n The arguments passed to this method depend on the format.\n format : str or None\n cache : bool\n Whether to cache the results of reading in the data.\n **kwargs\n The arguments passed to this method depend on the format.\n\n Returns\n -------\n object or None\n The output of the registered reader.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_05", "repo": "astropy", "question": "What does the `unit_parse_strict` parameter in `kepler_fits_reader` control, and what are its allowed values?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The `unit_parse_strict` parameter in `kepler_fits_reader` controls behavior when encountering invalid column units in FITS headers. Its default value is \"warn\", which emits a `UnitsWarning` and creates an `UnrecognizedUnit`. The allowed values are \"raise\", \"warn\", and \"silent\", which correspond to the values allowed by the `parse_strict` argument of `astropy.units.core.Unit`. This parameter determines how strictly the reader handles non-standard or invalid unit strings found in Kepler/TESS FITS file headers.", "rubric": [ "Explains that it controls behavior when encountering invalid column units in FITS headers", "States the default value is 'warn'", "Mentions that 'warn' emits a UnitsWarning and creates an UnrecognizedUnit", "Lists the allowed values: 'raise', 'warn', and 'silent'", "Notes that these values correspond to the parse_strict argument of astropy.units.core.Unit" ], "key_files": [ "astropy/timeseries/io/kepler.py" ], "source_doc": "[docstring: astropy/timeseries/io/kepler.py] astropy.timeseries.io.kepler.kepler_fits_reader\nThis serves as the FITS reader for KEPLER or TESS files within\n astropy-timeseries.\n\n This function should generally not be called directly, and instead this\n time series reader should be accessed with the\n :meth:`~astropy.timeseries.TimeSeries.read` method::\n\n >>> from astropy.timeseries import TimeSeries\n >>> ts = TimeSeries.read('kplr33122.fits', format='kepler.fits') # doctest: +SKIP\n\n Parameters\n ----------\n filename : `str` or `pathlib.Path`\n File to load.\n unit_parse_strict : str, optional\n Behaviour when encountering invalid column units in the FITS header.\n Default is \"warn\", which will emit a ``UnitsWarning`` and create a\n :class:`~astropy.units.core.UnrecognizedUnit`.\n Values are the ones allowed by the ``parse_strict`` argument of\n :class:`~astropy.units.core.Unit`: ``raise``, ``warn`` and ``silent``.\n\n Returns\n -------\n ts : `~astropy.timeseries.TimeSeries`\n Data converted into a TimeSeries.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_07", "repo": "astropy", "question": "Where is the recommended way to create LogQuantity instances shown, and what subclasses are available for that purpose?", "category": "where", "sub_type": "feature_location", "gold_answer": "According to the documentation, typical usage of LogQuantity is through its FunctionQuantity subclasses rather than directly. The examples demonstrate using `u.Magnitude()` and `u.Decibel()` as the recommended entry points. For instance, `u.Magnitude(-2.5)` creates a magnitude quantity, `u.Magnitude(10.*u.count/u.second)` converts a physical quantity to its logarithmic equivalent, and `u.Decibel(1.*u.W, u.DecibelUnit(u.mW))` demonstrates specifying a different physical unit reference via the unit parameter. The recommended usage pattern is described in the Examples section with the note 'Typically, use is made of an FunctionQuantity subclass'.", "rubric": [ "Mentions that LogQuantity is typically used through its FunctionQuantity subclasses (Magnitude, Decibel, Dex) rather than directly", "Identifies that u.Magnitude() is one entry point, e.g., u.Magnitude(-2.5) or u.Magnitude(10.*u.count/u.second)", "Identifies that u.Decibel() is another entry point, e.g., u.Decibel(1.*u.W, u.DecibelUnit(u.mW))", "Notes that LogQuantity's Examples section contains the note about typical usage being through FunctionQuantity subclasses", "Mentions that the subclasses (Magnitude, Decibel, Dex) each set their own _unit_class (MagUnit, DecibelUnit, DexUnit)" ], "key_files": [ "astropy/units/function/logarithmic.py" ], "source_doc": "[docstring: astropy/units/function/logarithmic.py] astropy.units.function.logarithmic.LogQuantity\nastropy.units.function.logarithmic.LogQuantity:\n A representation of a (scaled) logarithm of a number with a unit.\n\n Parameters\n ----------\n value : number, `~astropy.units.Quantity`, `~astropy.units.LogQuantity`, or sequence of quantity-like.\n The numerical value of the logarithmic quantity. If a number or\n a `~astropy.units.Quantity` with a logarithmic unit, it will be\n converted to ``unit`` and the physical unit will be inferred from\n ``unit``. If a `~astropy.units.Quantity` with just a physical unit,\n it will converted to the logarithmic unit, after, if necessary,\n converting it to the physical unit inferred from ``unit``.\n\n unit : str, `~astropy.units.UnitBase`, or `~astropy.units.FunctionUnitBase`, optional\n For an `~astropy.units.FunctionUnitBase` instance, the\n physical unit will be taken from it; for other input, it will be\n inferred from ``value``. By default, ``unit`` is set by the subclass.\n\n dtype : `~numpy.dtype`, optional\n The ``dtype`` of the resulting Numpy array or scalar that will\n hold the value. If not provided, is is determined automatically\n from the input value.\n\n copy : bool, optional\n If `True` (default), then the value is copied. Otherwise, a copy will\n only be made if ``__array__`` returns a copy, if value is a nested\n sequence, or if a copy is needed to satisfy an explicitly given\n ``dtype``. (The `False` option is intended mostly for internal use,\n to speed up initialization where a copy is known to have been made.\n Use with care.)\n\n Examples\n --------\n Typically, use is made of an `~astropy.units.FunctionQuantity`\n subclass, as in::\n\n >>> import astropy.units as u\n >>> u.Magnitude(-2.5)\n \n >>> u.Magnitude(10.*u.count/u.second)\n \n >>> u.Decibel(1.*u.W, u.DecibelUnit(u.mW)) # doctest: +FLOAT_CMP\n ", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_06", "repo": "astropy", "question": "Why does the `extirpolate` function exist and what algorithm or reference is it based on?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The `extirpolate` function is based on the C implementation of the `spread()` function presented in Numerical Recipes in C, Second Edition (Press et al. 1989; p.583). The function's purpose is to extirpolate values (x, y) onto an integer grid range(N) using Lagrange polynomial weights on the M nearest points. The parameter N should be larger than the maximum of x for best performance. The function preserves the property that weighted sums of the original data equal weighted sums of the extirpolated data on the integer grid, as demonstrated in the docstring example where np.sum(y * f(x)) equals np.sum(y_hat * f(x_hat)).", "rubric": [ "Mentions it is based on the C implementation of spread() from Numerical Recipes in C, Second Edition (Press et al. 1989; p.583)", "Explains that the function extirpolates values (x, y) onto an integer grid range(N) using Lagrange polynomial weights on the M nearest points", "Notes that N should be larger than the maximum of x for best performance", "Describes the key property that weighted sums of the original data equal weighted sums of the extirpolated data on the integer grid (np.sum(y * f(x)) == np.sum(y_hat * f(x_hat)))" ], "key_files": [ "astropy/timeseries/periodograms/lombscargle/implementations/utils.py" ], "source_doc": "[docstring: astropy/timeseries/periodograms/lombscargle/implementations/utils.py] astropy.timeseries.periodograms.lombscargle.implementations.utils.extirpolate\nExtirpolate the values (x, y) onto an integer grid range(N),\n using lagrange polynomial weights on the M nearest points.\n\n Parameters\n ----------\n x : array-like\n array of abscissas\n y : array-like\n array of ordinates\n N : int\n number of integer bins to use. For best performance, N should be larger\n than the maximum of x\n M : int\n number of adjoining points on which to extirpolate.\n\n Returns\n -------\n yN : ndarray\n N extirpolated values associated with range(N)\n\n Examples\n --------\n >>> rng = np.random.default_rng(0)\n >>> x = 100 * rng.random(20)\n >>> y = np.sin(x)\n >>> y_hat = extirpolate(x, y)\n >>> x_hat = np.arange(len(y_hat))\n >>> f = lambda x: np.sin(x / 10)\n >>> np.allclose(np.sum(y * f(x)), np.sum(y_hat * f(x_hat)))\n True\n\n Notes\n -----\n This code is based on the C implementation of spread() presented in\n Numerical Recipes in C, Second Edition (Press et al. 1989; p.583).", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_08", "repo": "astropy", "question": "How do you read a pre-2023 style IERS B file using the IERS_B class, and what non-default arguments are required?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "To read a pre-2023 style IERS B file (typically named something like `eopc04_IAU2000.62-now`), you need to call `IERS_B.read()` with two non-default arguments: (1) a custom `readme` parameter pointing to the file `ReadMe.eopc04_IAU2000` (found in `data/ReadMe.eopc04_IAU2000` within the `astropy.utils.iers` package), and (2) `data_start=14` instead of the default value of 6. The default `data_start=6` is appropriate for the standard (post-2023) IERS files, but pre-2023 files have a different header structure requiring the data to start at row 14. For example:\n\n```python\nfrom astropy.utils.iers import IERS_B\nfrom astropy.utils.data import get_pkg_data_filename\nold_style_file = get_pkg_data_filename(\n \"tests/data/iers_b_old_style_excerpt\",\n package=\"astropy.utils.iers\")\niers_b = IERS_B.read(\n old_style_file,\n readme=get_pkg_data_filename(\"data/ReadMe.eopc04_IAU2000\",\n package=\"astropy.utils.iers\"),\n data_start=14)\n```", "rubric": [ "Mentions passing a custom `readme` parameter pointing to `ReadMe.eopc04_IAU2000`", "Mentions setting `data_start=14` instead of the default value of 6", "Explains that the default `data_start=6` is for standard/post-2023 IERS files while pre-2023 files need 14 due to a different header structure", "Shows or describes the correct usage pattern (e.g., using `get_pkg_data_filename` with `package='astropy.utils.iers'` to locate the readme and data files)" ], "key_files": [ "astropy/utils/iers/iers.py" ], "source_doc": "[docstring: astropy/utils/iers/iers.py] astropy.utils.iers.iers.IERS_B\nastropy.utils.iers.iers.IERS_B:\n IERS Table class targeted to IERS B, provided by IERS itself.\n\n These are final values; see https://www.iers.org/IERS/EN/Home/home_node.html\n\n Notes\n -----\n If the package IERS B file (``iers.IERS_B_FILE``) is out of date, a new\n version can be downloaded from ``iers.IERS_B_URL``.\n\n See `~astropy.utils.iers.IERS_B.read` for instructions on how to read\n a pre-2023 style IERS B file (usually named ``eopc04_IAU2000.62-now``).\n\nastropy.utils.iers.iers.IERS_B.read:\n Read IERS-B table from a eopc04.* file provided by IERS.\n\n Parameters\n ----------\n file : str or os.PathLike[str]\n full path to ascii file holding IERS-B data.\n Defaults to package version, ``iers.IERS_B_FILE``.\n readme : str or os.PathLike[str]\n full path to ascii file holding CDS-style readme.\n Defaults to package version, ``iers.IERS_B_README``.\n data_start : int\n Starting row. Default is 6, appropriate for standard IERS files.\n\n Returns\n -------\n ``IERS_B`` class instance\n\n Notes\n -----\n To read a pre-2023 style IERS B file (usually named something like\n ``eopc04_IAU2000.62-now``), do something like this example with an\n excerpt that is used for testing::\n\n >>> from astropy.utils.iers import IERS_B\n >>> from astropy.utils.data import get_pkg_data_filename\n >>> old_style_file = get_pkg_data_filename(\n ... \"tests/data/iers_b_old_style_excerpt\",\n ... package=\"astropy.utils.iers\")\n >>> iers_b = IERS_B.read(\n ... old_style_file,\n ... readme=get_pkg_data_filename(\"data/ReadMe.eopc04_IAU2000\",\n ... package=\"astropy.utils.iers\"),\n ... data_start=14)\n\nastropy.utils.iers.iers.IERS_B.ut1_utc_source:\n Set UT1-UTC source flag for entries in IERS table.\n\nastropy.utils.iers.iers.IERS_B.dcip_source:\n Set CIP correction source flag for entries in IERS table.\n\nastropy.utils.iers.iers.IERS_B.pm_source:\n Set PM source flag for entries in IERS table.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_09", "repo": "astropy", "question": "What are the key dependencies and default behaviors of the MetaData descriptor class?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The MetaData descriptor depends on several key components and has specific default behaviors documented in its docstring: (1) The default factory for the meta attribute is OrderedDict, meaning when no meta is provided (or None is passed), an empty OrderedDict is created. (2) When the copy parameter is True (which is the default), the value is deepcopied before setting rather than saved as a reference. (3) When MetaData is accessed from the class itself (rather than an instance), it returns None, because metadata exists on instances not the class. (4) The default_factory parameter must be a callable that returns a Mapping object. These behaviors trace dependencies to collections.OrderedDict as the default metadata container, copy.deepcopy for the copy behavior, and collections.abc.Mapping as the type constraint for both the set value and the default_factory return type.", "rubric": [ "Identifies OrderedDict as the default factory for the meta attribute when None is passed or no meta is provided", "Explains that the copy parameter defaults to True and uses deepcopy before setting the value", "States that accessing MetaData from the class (not an instance) returns None", "Notes that default_factory must be a callable returning a Mapping object", "Identifies dependencies on collections.OrderedDict, copy.deepcopy, and collections.abc.Mapping" ], "key_files": [ "astropy/utils/metadata/core.py" ], "source_doc": "[docstring: astropy/utils/metadata/core.py] astropy.utils.metadata.core.MetaData\nastropy.utils.metadata.core.MetaData:\n A descriptor for classes that have a ``meta`` property.\n\n This can be set to any valid :class:`~collections.abc.Mapping`.\n\n Parameters\n ----------\n doc : `str`, optional\n Documentation for the attribute of the class.\n Default is ``\"\"``.\n\n .. versionadded:: 1.2\n\n copy : `bool`, optional\n If ``True`` the value is deepcopied before setting, otherwise it\n is saved as reference.\n Default is ``True``.\n\n .. versionadded:: 1.2\n\n default_factory : Callable[[], Mapping], optional keyword-only\n The factory to use to create the default value of the ``meta``\n attribute. This must be a callable that returns a `Mapping` object.\n Default is `OrderedDict`, creating an empty `OrderedDict`.\n\n .. versionadded:: 6.0\n\n Examples\n --------\n ``MetaData`` can be used as a descriptor to define a ``meta`` attribute`.\n\n >>> class Foo:\n ... meta = MetaData()\n ... def __init__(self, meta=None):\n ... self.meta = meta\n\n ``Foo`` can be instantiated with a ``meta`` argument.\n\n >>> foo = Foo(meta={'a': 1, 'b': 2})\n >>> foo.meta\n {'a': 1, 'b': 2}\n\n The default value of ``meta`` is an empty :class:`~collections.OrderedDict`.\n This can be set by passing ``None`` to the ``meta`` argument.\n\n >>> foo = Foo()\n >>> foo.meta\n OrderedDict()\n\n If an :class:`~collections.OrderedDict` is not a good default metadata type then\n the ``default_factory`` keyword can be used to set the default to a different\n `Mapping` type, when the class is defined.'\n\n >>> class Bar:\n ... meta = MetaData(default_factory=dict)\n ... def __init__(self, meta=None):\n ... self.meta = meta\n\n >>> Bar().meta\n {}\n\n When accessed from the class ``.meta`` returns `None` since metadata is\n on the class' instances, not the class itself.\n\n >>> print(Foo.meta)\n None", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "astropy_gen_10", "repo": "astropy", "question": "Why aren't new MergeStrategy subclasses enabled by default when they're registered?", "category": "why", "sub_type": "performance", "gold_answer": "New merge strategies are not enabled by default as a deliberate design decision to prevent inadvertently changing the behavior of unrelated code that is performing metadata merge operations. When a custom MergeStrategy subclass is defined, it is automatically registered to be available for use in merging, but it remains disabled until explicitly enabled through the enable_merge_strategies context manager. This design ensures that merely defining a merge strategy class in one part of a codebase cannot unexpectedly alter how metadata merging works in completely unrelated parts of the application. The context manager pattern provides a scoped, temporary activation that limits the impact of custom strategies to only the code blocks where they are intentionally needed.", "rubric": [ "Explains that it prevents inadvertently changing behavior of unrelated code performing metadata merge operations", "Mentions that subclasses are automatically registered in MERGE_STRATEGIES upon definition but remain disabled (enabled = False)", "Describes the enable_merge_strategies context manager as the mechanism for scoped/temporary activation", "Notes that this design ensures defining a strategy in one part of code doesn't unexpectedly alter merging in other parts" ], "key_files": [ "astropy/utils/metadata/merge.py" ], "source_doc": "[docstring: astropy/utils/metadata/merge.py] astropy.utils.metadata.merge.enable_merge_strategies\nContext manager to temporarily enable one or more custom metadata merge\n strategies.\n\n Examples\n --------\n Here we define a custom merge strategy that takes an int or float on\n the left and right sides and returns a list with the two values.\n\n >>> from astropy.utils.metadata import MergeStrategy\n >>> class MergeNumbersAsList(MergeStrategy):\n ... types = ((int, float), # left side types\n ... (int, float)) # right side types\n ... @classmethod\n ... def merge(cls, left, right):\n ... return [left, right]\n\n By defining this class the merge strategy is automatically registered to be\n available for use in merging. However, by default new merge strategies are\n *not enabled*. This prevents inadvertently changing the behavior of\n unrelated code that is performing metadata merge operations.\n\n In order to use the new merge strategy, use this context manager as in the\n following example::\n\n >>> from astropy.table import Table, vstack\n >>> from astropy.utils.metadata import enable_merge_strategies\n >>> t1 = Table([[1]], names=['a'])\n >>> t2 = Table([[2]], names=['a'])\n >>> t1.meta = {'m': 1}\n >>> t2.meta = {'m': 2}\n >>> with enable_merge_strategies(MergeNumbersAsList):\n ... t12 = vstack([t1, t2])\n >>> t12.meta['m']\n [1, 2]\n\n One can supply further merge strategies as additional arguments to the\n context manager.\n\n As a convenience, the enabling operation is actually done by checking\n whether the registered strategies are subclasses of the context manager\n arguments. This means one can define a related set of merge strategies and\n then enable them all at once by enabling the base class. As a trivial\n example, *all* registered merge strategies can be enabled with::\n\n >>> with enable_merge_strategies(MergeStrategy):\n ... t12 = vstack([t1, t2])\n\n Parameters\n ----------\n *merge_strategies : :class:`~astropy.utils.metadata.MergeStrategy` class\n Merge strategies that will be enabled.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_02", "repo": "sphinx", "question": "Why does the Sphinx extension tutorial's conf.py example use sys.path.append to add the _ext directory?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The reason `sys.path.append` is needed in conf.py when using a custom Sphinx extension is because the extension has not been installed as a Python package. Since the extension lives in a local `_ext` directory rather than being a proper installed package, the Python path must be modified so that Sphinx can locate and import the extension module. Without this modification, Sphinx would not be able to find the extension because it only searches installed packages and directories already on the Python path. The documentation explicitly states this rationale in a tip: 'Because we haven't installed our extension as a Python package, we need to modify the Python path so Sphinx can find our extension. This is why we need the call to sys.path.append.'", "rubric": [ "States that the extension has not been installed as a Python package", "Explains that Python/Sphinx cannot find the extension module without modifying sys.path because it only searches installed packages and directories already on the path", "Notes that the extension lives in a local directory (like _ext) rather than being properly packaged/installed" ], "key_files": [ "doc/development/tutorials/extending_syntax.rst" ], "source_doc": "[doc_file: doc/development/tutorials/extending_syntax.rst] Using the extension\nThe extension has to be declared in your :file:`conf.py` file to make Sphinx\naware of it. There are two steps necessary here:\n\n#. Add the :file:`_ext` directory to the `Python path`_ using\n ``sys.path.append``. This should be placed at the top of the file.\n\n#. Update or create the :confval:`extensions` list and add the extension file\n name to the list\n\nFor example:\n\n.. code-block:: python\n\n import sys\n from pathlib import Path\n\n sys.path.append(str(Path('_ext').resolve()))\n\n extensions = ['helloworld']\n\n.. tip::\n\n Because we haven't installed our extension as a `Python package`_, we need to\n modify the `Python path`_ so Sphinx can find our extension. This is why we\n need the call to ``sys.path.append``.\n\nYou can now use the extension in a file. For example:\n\n.. code-block:: rst\n\n Some intro text here...\n\n .. hello:: world\n\n Some text with a :hello:`world` role.\n\nThe sample above would generate:\n\n.. code-block:: text\n\n Some intro text here...\n\n Hello world!\n\n Some text with a hello world! role.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_04", "repo": "sphinx", "question": "How does the Sphinx tutorial set up and use doctests to keep documentation synchronized with code?", "category": "how", "sub_type": "system_design", "gold_answer": "To enable Sphinx to import your project's code for doctests, you modify `conf.py` by inserting the project's root directory into `sys.path` using `sys.path.insert(0, str(Path(__file__).resolve().parents[2]))`. This is placed at the beginning of `conf.py`. Then you enable the `sphinx.ext.doctest` extension in the `extensions` list. Doctests are written in reStructuredText files using the `>>>` prompt (the standard Python interpreter prompt) followed by the expected output on the next line. When you run `make doctest`, Sphinx executes these code snippets and compares the actual output against the expected output specified in the documentation. If they don't match, Sphinx reports both the expected and actual results for easy examination. An alternative to the `sys.path` manipulation approach is to create a `pyproject.toml` file and make the code installable so it behaves like any other Python library, but the `sys.path` approach is simpler. The purpose of doctests is to keep documentation and code synchronized by verifying that code snippets in the documentation produce the documented results when the documentation is built.", "rubric": [ "Explains that sys.path is modified in conf.py using sys.path.insert(0, str(Path(__file__).resolve().parents[2])) so Sphinx can import the project code", "Mentions enabling the sphinx.ext.doctest extension in the extensions list in conf.py", "Describes that doctests use the >>> prompt followed by expected output on the next line in reStructuredText files", "Explains that running 'make doctest' executes the code snippets and compares actual output to expected output", "Notes that on failure, Sphinx reports both expected and actual results", "Mentions the alternative approach of creating a pyproject.toml to make code installable instead of modifying sys.path", "States the purpose of doctests is to keep documentation and code synchronized" ], "key_files": [ "doc/tutorial/describing-code.rst" ], "source_doc": "[doc_file: doc/tutorial/describing-code.rst] Including doctests in your documentation\nSince you are now describing code from a Python library, it will become useful\nto keep both the documentation and the code as synchronized as possible.\nOne of the ways to do that in Sphinx is to include code snippets in the\ndocumentation, called *doctests*, that are executed when the documentation is\nbuilt.\n\nTo demonstrate doctests and other Sphinx features covered in this tutorial,\nSphinx will need to be able to import the code. To achieve that, write this\nat the beginning of ``conf.py``:\n\n.. code-block:: python\n :caption: docs/source/conf.py\n :emphasize-lines: 3-5\n\n # If extensions (or modules to document with autodoc) are in another directory,\n # add these directories to sys.path here.\n import sys\n from pathlib import Path\n sys.path.insert(0, str(Path(__file__).resolve().parents[2]))\n\n.. note::\n\n An alternative to changing the :py:data:`sys.path` variable is to create a\n ``pyproject.toml`` file and make the code installable,\n so it behaves like any other Python library. However, the ``sys.path``\n approach is simpler.\n\nThen, before adding doctests to your documentation, enable the\n:doc:`doctest ` extension in ``conf.py``:\n\n.. code-block:: python\n :caption: docs/source/conf.py\n :emphasize-lines: 3\n\n extensions = [\n 'sphinx.ext.duration',\n 'sphinx.ext.doctest',\n ]\n\nNext, write a doctest block as follows:\n\n.. code-block:: rst\n :caption: docs/source/usage.rst\n\n >>> import lumache\n >>> lumache.get_random_ingredients()\n ['shells', 'gorgonzola', 'parsley']\n\nDoctests include the Python instructions to be run preceded by ``>>>``,\nthe standard Python interpreter prompt, as well as the expected output\nof each instruction. This way, Sphinx can check whether the actual output\nmatches the expected one.\n\nTo observe how a doctest failure looks like (rather than a code error as\nabove), let's write the return value incorrectly first. Therefore, add a\nfunction ``get_random_ingredients`` like this:\n\n.. code-block:: python\n :caption: lumache.py\n\n def get_random_ingredients(kind=None):\n return [\"eggs\", \"bacon\", \"spam\"]\n\nYou can now run ``make doctest`` to execute the doctests of your documentation.\nInitially this will display an error, since the actual code does not behave\nas specified:\n\n.. code-block:: console\n\n (.venv) $ make doctest\n Running Sphinx v4.2.0\n loading pickled environment... done\n ...\n running tests...\n\n Document: usage\n ---------------\n **********************************************************************\n File \"usage.rst\", line 44, in default\n Failed example:\n lumache.get_random_ingredients()\n Expected:\n ['shells', 'gorgonzola', 'parsley']\n Got:\n ['eggs', 'bacon', 'spam']\n **********************************************************************\n ...\n make: *** [Makefile:20: doctest] Error 1\n\nAs you can see, doctest reports the expected and the actual results,\nfor easy examination. It is now time to fix the function:\n\n.. code-block:: python\n :caption: lumache.py\n :emphasize-lines: 2\n\n def get_random_ingredients(kind=None):\n return [\"shells\", \"gorgonzola\", \"parsley\"]\n\nAnd finally, ``make doctest`` reports success!\n\nFor big projects though, this manual approach can become a bit tedious.\nIn the next section, you will see :doc:`how to automate the\nprocess `.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_03", "repo": "sphinx", "question": "Where is the document name format defined, and what normalization does Sphinx apply to convert file paths into docnames?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "According to Sphinx's glossary, document names are always relative to the source directory, with the file extension stripped and path separators converted to slashes. There should be no leading or trailing slash. For example, valid document names are 'index', 'library/zipfile', or 'reference/datamodel/types'. This abstraction exists because reStructuredText source files can have different extensions (some people use .txt, some use .rst, configurable via source_suffix) and different operating systems have different path separators. All values, parameters, and references to 'documents' in Sphinx expect this normalized document name format.", "rubric": [ "Document names are relative to the source directory (no absolute paths)", "The file extension/suffix is stripped from the path", "Path separators are converted to forward slashes (SEP = '/')", "Unicode normalization (NFC) is applied via path_stabilize", "The conversion is implemented in Project.path2doc using path_stabilize and removesuffix", "source_suffix configuration determines which extensions are recognized and stripped", "Examples like 'index', 'library/zipfile' (with slash separators, no extension) represent valid docnames" ], "key_files": [ "doc/glossary.rst" ], "source_doc": "[doc_file: doc/glossary.rst] Glossary\n.. glossary::\n\n builder\n A class (inheriting from :class:`~sphinx.builders.Builder`) that takes\n parsed documents and performs an action on them. Normally, builders\n translate the documents to an output format, but it is also possible to\n use builders that e.g. check for broken links in the documentation, or\n build coverage information.\n\n See :doc:`/usage/builders/index` for an overview over Sphinx's built-in\n builders.\n\n configuration directory\n The directory containing :file:`conf.py`. By default, this is the same as\n the :term:`source directory`, but can be set differently with the **-c**\n command-line option.\n\n directive\n A reStructuredText markup element that allows marking a block of content\n with special meaning. Directives are supplied not only by docutils, but\n Sphinx and custom extensions can add their own. The basic directive\n syntax looks like this:\n\n .. code-block:: rst\n\n .. directive-name:: argument ...\n :option: value\n\n Content of the directive.\n\n See :ref:`rst-directives` for more information.\n\n document name\n Since reStructuredText source files can have different extensions\n (some people like ``.txt``, some like ``.rst`` -- the extension can be\n configured with :confval:`source_suffix`)\n and different OSes have different path\n separators, Sphinx abstracts them: :dfn:`document names` are always\n relative to the :term:`source directory`, the extension is stripped, and\n path separators are converted to slashes. All values, parameters and such\n referring to \"documents\" expect such document names.\n\n Examples for document names are ``index``, ``library/zipfile``, or\n ``reference/datamodel/types``. Note that there is no leading or trailing\n slash.\n\n domain\n A domain is a collection of markup (reStructuredText :term:`directive`\\ s\n and :term:`role`\\ s) to describe and link to :term:`object`\\ s belonging\n together, e.g. elements of a programming language. Directive and role\n names in a domain have names like ``domain:name``, e.g. ``py:function``.\n\n Having domains means that there are no naming problems when one set of\n documentation wants to refer to e.g. C++ and Python classes. It also\n means that extensions that support the documentation of whole new\n languages are much easier to write.\n\n For more information, refer to :doc:`/usage/domains/index`.\n\n environment\n A structure where information about all documents under the root is saved,\n and used for cross-referencing. The environment is pickled after the\n parsing stage, so that successive runs only need to read and parse new and\n changed documents.\n\n extension\n A custom :term:`role`, :term:`directive` or other aspect of Sphinx that\n allows users to modify any aspect of the build process within Sphinx.\n\n For more information, refer to :doc:`/usage/extensions/index`.\n\n master document\n root document\n The document that contains the root :rst:dir:`toctree` directive.\n\n object\n The basic building block of Sphinx documentation. Every \"object\n directive\" (e.g. :rst:dir:`py:function` or :rst:dir:`object`) creates such\n a block; and most objects can be cross-referenced to.\n\n RemoveInSphinxXXXWarning\n The feature which is warned will be removed in Sphinx-XXX version.\n It usually caused from Sphinx extensions which is using deprecated.\n See also :ref:`when-deprecation-warnings-are-displayed`.\n\n role\n A reStructuredText markup element that allows marking a piece of text.\n Like directives, roles are extensible. The basic syntax looks like this:\n ``:rolename:`content```. See :ref:`rst-inline-markup` for details.\n\n source directory\n The directory which, including its subdirectories, contains all source\n files for one Sphinx project.\n\n reStructuredText\n An easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and\n parser system.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_01", "repo": "sphinx", "question": "What do the `run` methods of Sphinx roles and directives return, and how does the docutils node hierarchy distinguish their outputs?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "When a Sphinx role's `run` method executes, it returns a tuple containing two elements: (1) a list of inline-level docutils nodes to be processed by Sphinx, and (2) an (optional) list of system message nodes. In contrast, a directive's `run` method returns a list of block-level docutils nodes to be processed by Sphinx. This distinction is important because docutils nodes follow a hierarchy where 'document' nodes should only contain block-level nodes (such as paragraph, section, table), while 'paragraph' nodes should only contain inline-level nodes (such as text, emphasis, strong). The document structure is described as an 'Abstract Syntax Tree' (AST) that represents content in a structured way that is generally independent of any one input format (rST, MyST, etc) or output format (HTML, LaTeX, etc).", "rubric": [ "States that a role's run method returns a tuple of two lists: inline-level docutils nodes and system message nodes", "States that a directive's run method returns a list of block-level docutils nodes", "Explains that document nodes should only contain block-level nodes (e.g., paragraph, section, table)", "Explains that paragraph nodes should only contain inline-level nodes (e.g., text, emphasis, strong)", "Mentions that the document structure is an Abstract Syntax Tree (AST) representing content independently of input/output format" ], "key_files": [ "doc/development/tutorials/extending_syntax.rst" ], "source_doc": "[doc_file: doc/development/tutorials/extending_syntax.rst] Writing the extension\nOpen :file:`helloworld.py` and paste the following code in it:\n\n.. literalinclude:: examples/helloworld.py\n :language: python\n :linenos:\n\nSome essential things are happening in this example:\n\nThe role class\n...............\n\nOur new role is declared in the ``HelloRole`` class.\n\n.. literalinclude:: examples/helloworld.py\n :language: python\n :linenos:\n :pyobject: HelloRole\n\nThis class extends the :class:`.SphinxRole` class.\nThe class contains a ``run`` method,\nwhich is a requirement for every role.\nIt contains the main logic of the role and it\nreturns a tuple containing:\n\n- a list of inline-level docutils nodes to be processed by Sphinx.\n- an (optional) list of system message nodes\n\nThe directive class\n...................\n\nOur new directive is declared in the ``HelloDirective`` class.\n\n.. literalinclude:: examples/helloworld.py\n :language: python\n :linenos:\n :pyobject: HelloDirective\n\nThis class extends the :class:`.SphinxDirective` class.\nThe class contains a ``run`` method,\nwhich is a requirement for every directive.\nIt contains the main logic of the directive and it\nreturns a list of block-level docutils nodes to be processed by Sphinx.\nIt also contains a ``required_arguments`` attribute,\nwhich tells Sphinx how many arguments are required for the directive.\n\nWhat are docutils nodes?\n........................\n\nWhen Sphinx parses a document,\nit creates an \"Abstract Syntax Tree\" (AST) of nodes\nthat represent the content of the document in a structured way,\nthat is generally independent of any one\ninput (rST, MyST, etc) or output (HTML, LaTeX, etc) format.\nIt is a tree because each node can have children nodes, and so on:\n\n.. code-block:: xml\n\n \n \n \n Hello world!\n\nThe docutils_ package provides many `built-in nodes `_,\nto represent different types of content such as\ntext, paragraphs, references, tables, etc.\n\nEach node type generally only accepts a specific set of direct child nodes,\nfor example the ``document`` node should only contain \"block-level\" nodes,\nsuch as ``paragraph``, ``section``, ``table``, etc,\nwhilst the ``paragraph`` node should only contain \"inline-level\" nodes,\nsuch as ``text``, ``emphasis``, ``strong``, etc.\n\n.. seealso::\n\n The docutils documentation on\n `creating directives `_, and\n `creating roles `_.\n\nThe ``setup`` function\n......................\n\nThis function is a requirement.\nWe use it to plug our new directive into Sphinx.\n\n.. literalinclude:: examples/helloworld.py\n :language: python\n :pyobject: setup\n\nThe simplest thing you can do is to call the\n:meth:`.Sphinx.add_role` and :meth:`.Sphinx.add_directive` methods,\nwhich is what we've done here.\nFor this particular call, the first argument is the name of the role/directive itself\nas used in a reStructuredText file.\nIn this case, we would use ``hello``. For example:\n\n.. code-block:: rst\n\n Some intro text here...\n\n .. hello:: world\n\n Some text with a :hello:`world` role.\n\nWe also return the :ref:`extension metadata ` that indicates the\nversion of our extension, along with the fact that it is safe to use the\nextension for both parallel reading and writing.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_06", "repo": "sphinx", "question": "Why does the builder's `compile_catalogs` method automatically convert .po files to .mo files during the build process?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The purpose of the version note about Sphinx 1.3 is to explain a historical change in the build workflow. Starting from Sphinx 1.3, `sphinx-build` (invoked by the make command) automatically builds .po files into .mo files during the documentation build process. This eliminated a manual step that was previously required. Users on Sphinx 1.2.x or earlier had to explicitly invoke `sphinx-intl build` before running the `make` command to compile the .po files into .mo files. This automation was introduced to simplify the translation workflow, removing the need for translators to remember an extra compilation step before building their translated documentation.", "rubric": [ "Explains that this automates a previously manual step (users had to run sphinx-intl build separately before Sphinx 1.3)", "Notes that this simplifies the translation/internationalization workflow by eliminating an extra compilation step", "Mentions that the behavior is controlled by the `gettext_auto_build` config value which defaults to True", "Explains that it checks if .mo files are outdated relative to .po files (via `is_outdated()`) before recompiling" ], "key_files": [ "doc/usage/advanced/intl.rst" ], "source_doc": "[doc_file: doc/usage/advanced/intl.rst] Quick guide\n`sphinx-intl`_ is a useful tool to work with Sphinx translation flow. This\nsection describe an easy way to translate with *sphinx-intl*.\n\n#. Install `sphinx-intl`_.\n\n .. code-block:: console\n\n $ pip install sphinx-intl\n\n#. Add configurations to :file:`conf.py`.\n\n ::\n\n locale_dirs = ['locale/'] # path is example but recommended.\n gettext_compact = False # optional.\n\n This case-study assumes that BUILDDIR is set to ``_build``,\n :confval:`locale_dirs` is set to ``locale/`` and :confval:`gettext_compact`\n is set to ``False`` (the Sphinx document is already configured as such).\n\n#. Extract translatable messages into pot files.\n\n .. code-block:: console\n\n $ make gettext\n\n The generated pot files will be placed in the ``_build/gettext`` directory.\n If you want to customize the output beyond what can be done via the\n :ref:`intl-options`, the\n :download:`default pot file template <../../../sphinx/templates/gettext/message.pot.jinja>`\n can be replaced by a custom :file:`message.pot.jinja` file placed in any\n directory listed in :confval:`templates_path`.\n\n#. Generate po files.\n\n We'll use the pot files generated in the above step.\n\n .. code-block:: console\n\n $ sphinx-intl update -p _build/gettext -l de -l ja\n\n Once completed, the generated po files will be placed in the below\n directories:\n\n * ``./locale/de/LC_MESSAGES/``\n * ``./locale/ja/LC_MESSAGES/``\n\n#. Translate po files.\n\n As noted above, these are located in the ``./locale//LC_MESSAGES``\n directory. An example of one such file, from Sphinx, :file:`builders.po`, is\n given below.\n\n .. code-block:: po\n\n # a5600c3d2e3d48fc8c261ea0284db79b\n #: ../../builders.rst:4\n msgid \"Available builders\"\n msgstr \"\"\n\n Another case, msgid is multi-line text and contains reStructuredText syntax:\n\n .. code-block:: po\n\n # 302558364e1d41c69b3277277e34b184\n #: ../../builders.rst:9\n msgid \"\"\n \"These are the built-in Sphinx builders. More builders can be added by \"\n \":ref:`extensions `.\"\n msgstr \"\"\n \"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE \"\n \"BY TARGET LANGUAGE :ref:`EXTENSIONS ` FILL HERE.\"\n\n Please be careful not to break reStructuredText notation.\n Most po-editors will help you with that.\n\n#. Build translated document.\n\n You need a :confval:`language` parameter in :file:`conf.py` or you may also\n specify the parameter on the command line.\n\n For BSD/GNU make, run:\n\n .. code-block:: console\n\n $ make -e SPHINXOPTS=\"-D language='de'\" html\n\n For Windows :command:`cmd.exe`, run:\n\n .. code-block:: doscon\n\n > set SPHINXOPTS=-D language=de\n > .\\make.bat html\n\n For PowerShell, run:\n\n .. code-block:: ps1con\n\n PS> Set-Item env:SPHINXOPTS \"-D language=de\"\n PS> .\\make.bat html\n\nCongratulations! You got the translated documentation in the ``_build/html``\ndirectory.\n\n.. versionadded:: 1.3\n\n :program:`sphinx-build` that is invoked by make command will build po files\n into mo files.\n\n If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`\n command before :command:`make` command.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_07", "repo": "sphinx", "question": "Where is the WebSupport class located now and how should it be configured for building vs retrieving data?", "category": "where", "sub_type": "feature_location", "gold_answer": "Since Sphinx version 1.6, the WebSupport class has been moved from sphinx.websupport to sphinxcontrib.websupport. To use it, you need to add the 'sphinxcontrib-websupport' package to your dependencies and import the class from its new location. All interactions with the web support package should occur through the WebSupport class. When configuring it, if you do not provide a 'storage' argument, a new sqlite database will be created by default. The 'builddir' parameter should be used when creating a WebSupport object that will be used to build data, while 'datadir' should be used when creating an object that will be used to retrieve data. If you specify a custom 'staticdir', you will typically want to adjust 'staticroot' accordingly.", "rubric": [ "Mentions that WebSupport moved from sphinx.websupport to sphinxcontrib.websupport since Sphinx 1.6", "States that sphinxcontrib-websupport package needs to be added to dependencies", "Explains that all interactions with the web support package should occur through the WebSupport class", "Notes that if no 'storage' argument is provided, a new sqlite database is created by default", "Explains that 'builddir' is used when creating a WebSupport object for building data", "Explains that 'datadir' is used when creating a WebSupport object for retrieving data", "Notes that specifying a custom 'staticdir' typically means you should adjust 'staticroot' accordingly" ], "key_files": [ "doc/usage/advanced/websupport/api.rst" ], "source_doc": "[doc_file: doc/usage/advanced/websupport/api.rst] The WebSupport class\n.. class:: WebSupport\n\n The main API class for the web support package. All interactions with the\n web support package should occur through this class.\n\n The class takes the following keyword arguments:\n\n srcdir\n The directory containing reStructuredText source files.\n\n builddir\n The directory that build data and static files should be placed in. This\n should be used when creating a :class:`WebSupport` object that will be\n used to build data.\n\n datadir\n The directory that the web support data is in. This should be used when\n creating a :class:`WebSupport` object that will be used to retrieve data.\n\n search\n This may contain either a string (e.g. 'xapian') referencing a built-in\n search adapter to use, or an instance of a subclass of\n :class:`~.search.BaseSearch`.\n\n storage\n This may contain either a string representing a database uri, or an\n instance of a subclass of :class:`~.storage.StorageBackend`. If this is\n not provided, a new sqlite database will be created.\n\n moderation_callback\n A callable to be called when a new comment is added that is not\n displayed. It must accept one argument: a dictionary representing the\n comment that was added.\n\n staticdir\n If the static files should be created in a different location\n **and not in** ``'/static'``, this should be a string with the name of\n that location (e.g. ``builddir + '/static_files'``).\n\n .. note::\n If you specify ``staticdir``, you will typically want to adjust\n ``staticroot`` accordingly.\n\n staticroot\n If the static files are not served from ``'/static'``, this should be a\n string with the name of that location (e.g. ``'/static_files'``).\n\n docroot\n If the documentation is not served from the base path of a URL, this\n should be a string specifying that path (e.g. ``'docs'``).\n\n\n.. versionchanged:: 1.6\n\n WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport.\n Please add ``sphinxcontrib-websupport`` package in your dependency and use\n moved class instead.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_05", "repo": "sphinx", "question": "What are the different catalog file types in Sphinx's i18n system, and how is the granularity of translatable messages determined?", "category": "what", "sub_type": "concept_definition", "gold_answer": "In Sphinx internationalization, there are three types of catalog files that form a pipeline: 1) **Catalog templates** (.pot files) - these are produced by the MessageCatalogBuilder and contain messages in the original language only. 2) **Message catalogs** (.po files) - these are created by translators and contain a mapping from the original messages to foreign-language strings. 3) **Binary catalogs** (.mo files) - these are compiled from .po files using msgfmt for efficiency reasons, and are the files that Sphinx actually picks up automatically when discoverable via locale_dirs. The granularity of translation units is determined by doctree elements: every single element in the doctree becomes a single message, meaning lists get split into different chunks while large paragraphs remain as coarsely-grained as they were in the original document. This design grants seamless document updates while providing some context for translators in free-text passages. It is the maintainer's responsibility to split up paragraphs that are too large, as there is no sane automated way to do that.", "rubric": [ "Identifies .pot files (catalog templates) as produced by MessageCatalogBuilder", "Identifies .po files (message catalogs) as translator-created mappings between original and foreign-language strings", "Identifies .mo files (binary/compiled catalogs) as compiled from .po files via write_mo for use at build time", "Explains that locale_dirs configuration determines where catalogs are discovered", "Explains that translatable messages are extracted at the doctree element level (each translatable node becomes a single message unit)", "Notes that is_translatable determines which nodes qualify (TextElement nodes with source, images with alt/translatable, meta nodes, etc.)" ], "key_files": [ "doc/usage/advanced/intl.rst" ], "source_doc": "[doc_file: doc/usage/advanced/intl.rst] Sphinx internationalization details\n**gettext** [1]_ is an established standard for internationalization and\nlocalization. It naively maps messages in a program to a translated string.\nSphinx uses these facilities to translate whole documents.\n\nInitially project maintainers have to collect all translatable strings (also\nreferred to as *messages*) to make them known to translators. Sphinx extracts\nthese through invocation of :command:`sphinx-build -M gettext`.\n\nEvery single element in the doctree will end up in a single message which\nresults in lists being equally split into different chunks while large\nparagraphs will remain as coarsely-grained as they were in the original\ndocument. This grants seamless document updates while still providing a little\nbit of context for translators in free-text passages. It is the maintainer's\ntask to split up paragraphs which are too large as there is no sane automated\nway to do that.\n\nAfter Sphinx successfully ran the\n:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a\ncollection of ``.pot`` files in your output directory. These are **catalog\ntemplates** and contain messages in your original language *only*.\n\nThey can be delivered to translators which will transform them to ``.po`` files\n--- so called **message catalogs** --- containing a mapping from the original\nmessages to foreign-language strings.\n\n*gettext* compiles them into a binary format known as **binary catalogs**\nthrough :program:`msgfmt` for efficiency reasons. If you make these files\ndiscoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx\nwill pick them up automatically.\n\nAn example: you have a document :file:`usage.rst` in your Sphinx project. The\n*gettext* builder will put its messages into :file:`usage.pot`. Imagine you have\nSpanish translations [2]_ stored in :file:`usage.po` --- for your builds to\nbe translated you need to follow these instructions:\n\n* Compile your message catalog to a locale directory, say ``locale``, so it\n ends up in :file:`./locale/es/LC_MESSAGES/usage.mo` in your source directory\n (where ``es`` is the language code for Spanish.) ::\n\n msgfmt \"usage.po\" -o \"locale/es/LC_MESSAGES/usage.mo\"\n\n* Set :confval:`locale_dirs` to ``[\"locale/\"]``.\n* Set :confval:`language` to ``es`` (also possible via\n :option:`-D `).\n* Run your desired build.\n\n\nIn order to protect against mistakes, a warning is emitted if\ncross-references in the translated paragraph do not match those from the\noriginal. This can be turned off globally using the\n:confval:`suppress_warnings` configuration variable. Alternatively, to\nturn it off for one message only, end the message with ``#noqa`` like\nthis::\n\n Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse\n risus tortor, luctus id ultrices at. #noqa\n\n(Write ``\\#noqa`` in case you want to have \"#noqa\" literally in the\ntext. This does not apply to code blocks, where ``#noqa`` is ignored\nbecause code blocks do not contain references anyway.)\n\n.. versionadded:: 4.5\n The ``#noqa`` mechanism.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_08", "repo": "sphinx", "question": "How does the WebSupport class build documentation data, and what output structure does it produce?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "To build documentation data for the web support package, you create an instance of the WebSupport class (imported from sphinxcontrib.websupport) and call its build() method. You provide at minimum a srcdir (path to reStructuredText sources) and a builddir (path to the build output directory). Optionally, you can specify a search engine (e.g., search='xapian'). When build() is called, it reads the reStructuredText sources from srcdir and produces two subdirectories within builddir: (1) a directory named 'data' containing all data needed to display documents, search through documents, and add comments to documents (including pickle files representing documents, search indices, and node data for tracking where comments and other things are in a document), and (2) a directory named 'static' containing static files that should be served from the URL path '/static'. If you want to serve static files from a different path than '/static', you can provide the 'staticdir' keyword argument when creating the WebSupport object.", "rubric": [ "Mentions creating a WebSupport instance with srcdir and builddir parameters", "Mentions calling the build() method on the WebSupport instance", "Explains that srcdir points to the reStructuredText source files", "Explains that builddir receives the output and contains a 'data' subdirectory with pickle files, search indices, and node data", "Explains that builddir also contains a 'static' subdirectory for static files served from '/static'", "Mentions that the staticdir keyword argument can customize where static files are placed or served from" ], "key_files": [ "doc/usage/advanced/websupport/quickstart.rst" ], "source_doc": "[doc_file: doc/usage/advanced/websupport/quickstart.rst] Building documentation data\nTo make use of the web support package in your application you'll need to build\nthe data it uses. This data includes pickle files representing documents,\nsearch indices, and node data that is used to track where comments and other\nthings are in a document. To do this you will need to create an instance of the\n:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method::\n\n from sphinxcontrib.websupport import WebSupport\n\n support = WebSupport(srcdir='/path/to/rst/sources/',\n builddir='/path/to/build/outdir',\n search='xapian')\n\n support.build()\n\nThis will read reStructuredText sources from ``srcdir`` and place the necessary\ndata in ``builddir``. The ``builddir`` will contain two subdirectories: one\nnamed \"data\" that contains all the data needed to display documents, search\nthrough documents, and add comments to documents. The other directory will be\ncalled \"static\" and contains static files that should be served from \"/static\".\n\n.. note::\n\n If you wish to serve static files from a path other than \"/static\", you can\n do so by providing the *staticdir* keyword argument when creating the\n :class:`~.WebSupport` object.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_09", "repo": "sphinx", "question": "What happened to the sphinx.websupport module (including its search adapter interface) in version 1.6, and what replaced it?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The BaseSearch class, which defines the interface for search adapters, was moved from sphinx.websupport.search to sphinxcontrib.websupport.search in version 1.6. To create a custom search adapter, you subclass BaseSearch, create an instance of the new class, and pass that instance as the 'search' keyword argument when creating the WebSupport object. This means that any code depending on importing BaseSearch from sphinx.websupport.search would need to be updated to import from sphinxcontrib.websupport.search after version 1.6.", "rubric": [ "The sphinx.websupport module was deprecated in version 1.6", "It was replaced by sphinxcontrib-websupport (sphinxcontrib.websupport)", "The module was fully removed in version 2.0", "The search adapter base class (BaseSearch) moved from sphinx.websupport.search to sphinxcontrib.websupport.search" ], "key_files": [ "doc/usage/advanced/websupport/searchadapters.rst" ], "source_doc": "[doc_file: doc/usage/advanced/websupport/searchadapters.rst] Search adapters\nTo create a custom search adapter you will need to subclass the\n:class:`BaseSearch` class. Then create an instance of the new class and pass\nthat as the *search* keyword argument when you create the :class:`~.WebSupport`\nobject::\n\n support = WebSupport(srcdir=srcdir,\n builddir=builddir,\n search=MySearch())\n\nFor more information about creating a custom search adapter, please see the\ndocumentation of the :class:`BaseSearch` class below.\n\n.. class:: BaseSearch\n\n Defines an interface for search adapters.\n\n.. versionchanged:: 1.6\n\n BaseSearch class is moved to sphinxcontrib.websupport.search from\n sphinx.websupport.search.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "sphinx_gen_10", "repo": "sphinx", "question": "Why was sphinx.websupport separated into the sphinxcontrib-websupport package in version 1.6?", "category": "why", "sub_type": "performance", "gold_answer": "The StorageBackend class was moved from sphinx.websupport.storage to sphinxcontrib.websupport.storage in version 1.6. This relocation was part of a broader architectural change, likely to separate the websupport functionality into a contrib package (sphinxcontrib). The rationale for this move appears to be modularization\u2014extracting websupport storage backends from the core Sphinx package into the sphinxcontrib namespace, which allows the websupport functionality to be maintained and versioned independently. While performance isn't the primary driver here, modularization can improve maintenance efficiency and reduce the core package's footprint, allowing users who don't need websupport to avoid loading unnecessary code. The documentation specifically notes this change happened in version 1.6, which is critical migration guidance for anyone upgrading from earlier versions who had imports pointing to the old location.", "rubric": [ "The StorageBackend/websupport functionality was moved from sphinx.websupport to sphinxcontrib-websupport (or sphinxcontrib.websupport.storage)", "The move was for modularization\u2014separating websupport into an independent package that can be maintained and versioned separately", "This reduces the core Sphinx package's footprint so users who don't need websupport avoid loading unnecessary dependencies", "The changelog indicates sphinx.websupport was deprecated in 1.6 and slated for removal in Sphinx 2.0", "Issue #3660 shows that having websupport bundled caused Sphinx to always depend on sphinxcontrib-websupport and its dependencies even when not needed" ], "key_files": [ "doc/usage/advanced/websupport/storagebackends.rst" ], "source_doc": "[doc_file: doc/usage/advanced/websupport/storagebackends.rst] Storage backends\nTo create a custom storage backend you will need to subclass the\n:class:`StorageBackend` class. Then create an instance of the new class and\npass that as the *storage* keyword argument when you create the\n:class:`~.WebSupport` object::\n\n support = WebSupport(srcdir=srcdir,\n builddir=builddir,\n storage=MyStorage())\n\nFor more information about creating a custom storage backend, please see the\ndocumentation of the :class:`StorageBackend` class below.\n\n.. class:: StorageBackend\n\n Defines an interface for storage backends.\n\n.. versionchanged:: 1.6\n\n StorageBackend class is moved to sphinxcontrib.websupport.storage from\n sphinx.websupport.storage.", "verification_verdict": "warn", "verification_issues": [ "The claim about 'broader architectural change' is speculative and not stated in the documentation.", "The rationale about 'modularization' and 'extracting websupport storage backends from the core Sphinx package' is plausible but not explicitly stated in the documentation.", "The claim about 'allowing users who don't need websupport to avoid loading unnecessary code' is speculative and unsupported by the documentation.", "The mention of 'performance' and 'maintenance efficiency' and 'reduce the core package's footprint' are speculative extrapolations not found in the documentation.", "The claim about 'critical migration guidance for anyone upgrading from earlier versions who had imports pointing to the old location' is a reasonable inference but not explicitly stated." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_03", "repo": "xarray", "question": "Where does the `shortcut` parameter in DataArrayGroupBy's `map` method change behavior, and what assumptions must hold for it to be valid?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "When using `DataArrayGroupByBase.map` with the `shortcut` parameter set to True, the assumptions that must be satisfied are: (1) The action of `func` does not depend on any of the array metadata (attributes or coordinates) but only on the data and dimensions, and (2) The action of `func` creates arrays with homogeneous metadata, that is, with the same dimensions and attributes. When these conditions are met, the shortcut provides significant speedup, and the documentation notes this should be the case for many common groupby operations such as applying numpy ufuncs. Internally, the shortcut leverages `_iter_grouped_shortcut`, which is described as a fast version of `_iter_grouped` that yields Variables without metadata. The stacking heuristics used by `map` follow two rules: (1) if the dimension along which the group coordinate is defined is still present in the first grouped array after applying `func`, then stack over that dimension; (2) otherwise, stack over the new dimension given by the name of the grouping (the argument to the `groupby` function).", "rubric": [ "Explains that shortcut causes `_iter_grouped_shortcut` to be used instead of `_iter_grouped`, yielding Variables without metadata", "States assumption (1): func's action does not depend on array metadata (attributes or coordinates), only on data and dimensions", "States assumption (2): func creates arrays with homogeneous metadata (same dimensions and attributes)", "Mentions that these conditions provide significant speedup, applicable to common operations like numpy ufuncs", "Describes the stacking heuristics: (1) if the group dimension is still present after applying func, stack over that dimension; (2) otherwise, stack over the new dimension given by the groupby name" ], "key_files": [ "xarray/core/groupby.py" ], "source_doc": "[docstring: xarray/core/groupby.py] xarray.core.groupby.DataArrayGroupByBase\nxarray.core.groupby.DataArrayGroupByBase:\n GroupBy object specialized to grouping DataArray objects\n\nxarray.core.groupby.DataArrayGroupByBase._iter_grouped_shortcut:\n Fast version of `_iter_grouped` that yields Variables without\n metadata\n\nxarray.core.groupby.DataArrayGroupByBase.map:\n Apply a function to each array in the group and concatenate them\n together into a new array.\n\n `func` is called like `func(ar, *args, **kwargs)` for each array `ar`\n in this group.\n\n Apply uses heuristics (like `pandas.GroupBy.apply`) to figure out how\n to stack together the array. The rule is:\n\n 1. If the dimension along which the group coordinate is defined is\n still in the first grouped array after applying `func`, then stack\n over this dimension.\n 2. Otherwise, stack over the new dimension given by name of this\n grouping (the argument to the `groupby` function).\n\n Parameters\n ----------\n func : callable\n Callable to apply to each array.\n shortcut : bool, optional\n Whether or not to shortcut evaluation under the assumptions that:\n\n (1) The action of `func` does not depend on any of the array\n metadata (attributes or coordinates) but only on the data and\n dimensions.\n (2) The action of `func` creates arrays with homogeneous metadata,\n that is, with the same dimensions and attributes.\n\n If these conditions are satisfied `shortcut` provides significant\n speedup. This should be the case for many common groupby operations\n (e.g., applying numpy ufuncs).\n *args : tuple, optional\n Positional arguments passed to `func`.\n **kwargs\n Used to call `func(ar, **kwargs)` for each array `ar`.\n\n Returns\n -------\n applied : DataArray\n The result of splitting, applying and combining this array.\n\nxarray.core.groupby.DataArrayGroupByBase.apply:\n Backward compatible implementation of ``map``\n\n See Also\n --------\n DataArrayGroupBy.map\n\nxarray.core.groupby.DataArrayGroupByBase._combine:\n Recombine the applied objects like the original.\n\nxarray.core.groupby.DataArrayGroupByBase.reduce:\n Reduce the items in this group by applying `func` along some\n dimension(s).\n\n Parameters\n ----------\n func : callable\n Function which can be called in the form\n `func(x, axis=axis, **kwargs)` to return the result of collapsing\n an np.ndarray over an integer valued axis.\n dim : \"...\", str, Iterable of Hashable or None, optional\n Dimension(s) over which to apply `func`. If None, apply over the\n groupby dimension, if \"...\" apply over all dimensions.\n axis : int or sequence of int, optional\n Axis(es) over which to apply `func`. Only one of the 'dimension'\n and 'axis' arguments can be supplied. If neither are supplied, then\n `func` is calculated over all dimension for each group item.\n keep_attrs : bool, optional\n If True, the datasets's attributes (`attrs`) will be copied from\n the original object to the new one. If False (default), the new\n object will be returned without attributes.\n **kwargs : dict\n Additional keyword arguments passed on to `func`.\n\n Returns\n -------\n reduced : Array\n Array with summarized data and the indicated dimension(s)\n removed.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_02", "repo": "xarray", "question": "Why is `render_human_readable_nbytes` explicitly documented as imprecise rather than providing exact byte counts?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The `render_human_readable_nbytes` function is explicitly documented as being only a quick, approximate representation that should NOT be relied upon for precise needs. The design rationale is that it serves as a convenience display utility rather than an exact measurement tool. The documentation explicitly directs users who need exact byte counts to use the `nbytes` attribute directly instead. Additionally, the function includes an `attempt_constant_width` parameter whose purpose is to try to render a fixed-width representation for reasonable nbytes sizes \u2014 this is a formatting/display consideration to keep output aligned, not a precision guarantee. The function is intentionally imprecise by design, trading accuracy for human readability.", "rubric": [ "Explains that the function is designed as a quick/convenience display utility for human readability, not for precise measurement", "Mentions that users needing exact byte counts are directed to use the `nbytes` attribute directly", "Notes the `attempt_constant_width` parameter is for formatting/alignment purposes (fixed-width display), not precision", "Recognizes the function intentionally trades accuracy for readability (e.g., using rounded/approximate values with unit suffixes)" ], "key_files": [ "xarray/core/formatting.py" ], "source_doc": "[docstring: xarray/core/formatting.py] xarray.core.formatting.render_human_readable_nbytes\nRenders simple human-readable byte count representation\n\n This is only a quick representation that should not be relied upon for precise needs.\n\n To get the exact byte count, please use the ``nbytes`` attribute directly.\n\n Parameters\n ----------\n nbytes\n Byte count\n attempt_constant_width\n For reasonable nbytes sizes, tries to render a fixed-width representation.\n\n Returns\n -------\n Human-readable representation of the byte count", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_01", "repo": "xarray", "question": "What is the recommended pattern for using `attempt_import` with static type checkers, and why is it needed?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The `attempt_import` function in xarray is used to import optional dependencies and raise an informative error on failure. A key limitation documented is that static type checkers will not be able to infer the type of the returned module. To work around this, the recommended pattern is to precede the `attempt_import` call with a direct import of the module guarded by an `if TYPE_CHECKING` block. This preserves type checker functionality while still using the lazy/optional import mechanism at runtime. The pattern looks like:\n\n```python\nif TYPE_CHECKING:\n import zarr\nelse:\n zarr = attempt_import(\"zarr\")\n```\n\nThis ensures that type checkers (which only analyze the `TYPE_CHECKING` branch) can properly infer the module type, while at runtime the `attempt_import` function handles the optional dependency gracefully with an informative error if the module is not installed.", "rubric": [ "Explains that attempt_import is used to import optional dependencies and raise informative errors on failure", "Mentions that static type checkers cannot infer the type of the returned module from attempt_import", "Describes the TYPE_CHECKING guard pattern: a direct import under `if TYPE_CHECKING` with `attempt_import` in the `else` branch", "Shows or describes the concrete pattern (e.g., `if TYPE_CHECKING: import zarr` / `else: zarr = attempt_import('zarr')`)", "Explains that type checkers only analyze the TYPE_CHECKING branch while runtime uses attempt_import for graceful handling" ], "key_files": [ "xarray/core/utils.py" ], "source_doc": "[docstring: xarray/core/utils.py] xarray.core.utils.attempt_import\nImport an optional dependency, and raise an informative error on failure.\n\n Parameters\n ----------\n module : str\n Module to import. For example, ``'zarr'`` or ``'matplotlib.pyplot'``.\n\n Returns\n -------\n module : ModuleType\n The Imported module.\n\n Raises\n ------\n ImportError\n If the module could not be imported.\n\n Notes\n -----\n Static type checkers will not be able to infer the type of the returned module,\n so it is recommended to precede this function with a direct import of the module,\n guarded by an ``if TYPE_CHECKING`` block, to preserve type checker functionality.\n See the examples section below for a demonstration.\n\n Examples\n --------\n >>> from xarray.core.utils import attempt_import\n >>> if TYPE_CHECKING:\n ... import zarr\n ... else:\n ... zarr = attempt_import(\"zarr\")\n ...", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_04", "repo": "xarray", "question": "How does DatasetGroupByBase's map method decide which dimension to stack the results along after applying the function?", "category": "how", "sub_type": "system_design", "gold_answer": "The `DatasetGroupByBase.map` method uses heuristics (similar to `pandas.GroupBy.apply`) to determine how to stack the resulting datasets back together. The algorithm works as follows:\n\n1. After applying `func` to the first grouped item, the method checks whether the dimension along which the group coordinate is defined is still present in the result.\n2. If that dimension IS still present in the first grouped result, then the datasets are stacked over this original grouping dimension.\n3. If that dimension is NOT present in the first grouped result (e.g., because `func` reduced along it), then the datasets are stacked over a new dimension whose name is taken from the name of the grouping variable (i.e., the argument that was passed to the `groupby` function).\n\nThis heuristic-based approach means the stacking behavior is determined dynamically at runtime based on the output of the first group's function application, rather than being explicitly specified by the user.", "rubric": [ "Mentions that heuristics (similar to pandas GroupBy.apply) are used to determine stacking behavior", "Explains that the method checks whether the original grouping dimension is still present in the first applied result", "States that if the grouping dimension IS present in the result, stacking occurs over the original grouping dimension", "States that if the grouping dimension is NOT present in the result, stacking occurs over the dimension of the unique coordinate (named after the grouping variable)", "Notes that this determination is based on inspecting the first grouped result (applied_example via peek_at)" ], "key_files": [ "xarray/core/groupby.py" ], "source_doc": "[docstring: xarray/core/groupby.py] xarray.core.groupby.DatasetGroupByBase\nxarray.core.groupby.DatasetGroupByBase.map:\n Apply a function to each Dataset in the group and concatenate them\n together into a new Dataset.\n\n `func` is called like `func(ds, *args, **kwargs)` for each dataset `ds`\n in this group.\n\n Apply uses heuristics (like `pandas.GroupBy.apply`) to figure out how\n to stack together the datasets. The rule is:\n\n 1. If the dimension along which the group coordinate is defined is\n still in the first grouped item after applying `func`, then stack\n over this dimension.\n 2. Otherwise, stack over the new dimension given by name of this\n grouping (the argument to the `groupby` function).\n\n Parameters\n ----------\n func : callable\n Callable to apply to each sub-dataset.\n args : tuple, optional\n Positional arguments to pass to `func`.\n **kwargs\n Used to call `func(ds, **kwargs)` for each sub-dataset `ar`.\n\n Returns\n -------\n applied : Dataset\n The result of splitting, applying and combining this dataset.\n\nxarray.core.groupby.DatasetGroupByBase.apply:\n Backward compatible implementation of ``map``\n\n See Also\n --------\n DatasetGroupBy.map\n\nxarray.core.groupby.DatasetGroupByBase._combine:\n Recombine the applied objects like the original.\n\nxarray.core.groupby.DatasetGroupByBase.reduce:\n Reduce the items in this group by applying `func` along some\n dimension(s).\n\n Parameters\n ----------\n func : callable\n Function which can be called in the form\n `func(x, axis=axis, **kwargs)` to return the result of collapsing\n an np.ndarray over an integer valued axis.\n dim : ..., str, Iterable of Hashable or None, optional\n Dimension(s) over which to apply `func`. By default apply over the\n groupby dimension, with \"...\" apply over all dimensions.\n axis : int or sequence of int, optional\n Axis(es) over which to apply `func`. Only one of the 'dimension'\n and 'axis' arguments can be supplied. If neither are supplied, then\n `func` is calculated over all dimension for each group item.\n keep_attrs : bool, optional\n If True, the datasets's attributes (`attrs`) will be copied from\n the original object to the new one. If False (default), the new\n object will be returned without attributes.\n **kwargs : dict\n Additional keyword arguments passed on to `func`.\n\n Returns\n -------\n reduced : Dataset\n Array with summarized data and the indicated dimension(s)\n removed.\n\nxarray.core.groupby.DatasetGroupByBase.assign:\n Assign data variables by group.\n\n See Also\n --------\n Dataset.assign", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_05", "repo": "xarray", "question": "What is the `Indexes` class in xarray's core indexes module, and what does its constructor expect?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The `xarray.core.indexes.Indexes` class is an immutable proxy for Dataset or DataArray indexes. It functions as a mapping where keys are coordinate names and values are either pandas or xarray indexes. Beyond being a simple mapping, it also contains the indexed coordinate variables and provides utility methods. Notably, its constructor (`__init__`) is explicitly documented as 'not for public consumption,' meaning users should not instantiate this class directly. The constructor requires three parameters: `indexes` (a dict of indexes held by the object), `variables` (a dict of indexed coordinate variables that must have entries matching those of `indexes`), and `index_type` (the type of all indexes, which must be either `xarray.indexes.Index` or `pandas.Index`).", "rubric": [ "States that Indexes is an immutable proxy for Dataset or DataArray indexes", "Explains it is a mapping where keys are coordinate names and values are pandas or xarray indexes", "Mentions it also contains indexed coordinate variables and provides utility methods", "Notes the constructor is explicitly not for public consumption (not intended to be called directly by users)", "Describes the three constructor parameters: indexes (dict of indexes), variables (dict of indexed coordinate variables matching indexes entries), and index_type (type of all indexes, either xarray Index or pandas.Index)" ], "key_files": [ "xarray/core/indexes.py" ], "source_doc": "[docstring: xarray/core/indexes.py] xarray.core.indexes.Indexes\nxarray.core.indexes.Indexes:\n Immutable proxy for Dataset or DataArray indexes.\n\n It is a mapping where keys are coordinate names and values are either pandas\n or xarray indexes.\n\n It also contains the indexed coordinate variables and provides some utility\n methods.\n\nxarray.core.indexes.Indexes.__init__:\n Constructor not for public consumption.\n\n Parameters\n ----------\n indexes : dict\n Indexes held by this object.\n variables : dict\n Indexed coordinate variables in this object. Entries must\n match those of `indexes`.\n index_type : type\n The type of all indexes, i.e., either :py:class:`xarray.indexes.Index`\n or :py:class:`pandas.Index`.\n\nxarray.core.indexes.Indexes.get_unique:\n Return a list of unique indexes, preserving order.\n\nxarray.core.indexes.Indexes.is_multi:\n Return True if ``key`` maps to a multi-coordinate index,\n False otherwise.\n\nxarray.core.indexes.Indexes.get_all_coords:\n Return all coordinates having the same index.\n\n Parameters\n ----------\n key : hashable\n Index key.\n errors : {\"raise\", \"ignore\"}, default: \"raise\"\n If \"raise\", raises a ValueError if `key` is not in indexes.\n If \"ignore\", an empty tuple is returned instead.\n\n Returns\n -------\n coords : dict\n A dictionary of all coordinate variables having the same index.\n\nxarray.core.indexes.Indexes.get_all_dims:\n Return all dimensions shared by an index.\n\n Parameters\n ----------\n key : hashable\n Index key.\n errors : {\"raise\", \"ignore\"}, default: \"raise\"\n If \"raise\", raises a ValueError if `key` is not in indexes.\n If \"ignore\", an empty tuple is returned instead.\n\n Returns\n -------\n dims : dict\n A dictionary of all dimensions shared by an index.\n\nxarray.core.indexes.Indexes.group_by_index:\n Returns a list of unique indexes and their corresponding coordinates.\n\nxarray.core.indexes.Indexes.to_pandas_indexes:\n Returns an immutable proxy for Dataset or DataArray pandas indexes.\n\n Raises an error if this proxy contains indexes that cannot be coerced to\n pandas.Index objects.\n\nxarray.core.indexes.Indexes.copy_indexes:\n Return a new dictionary with copies of indexes, preserving\n unique indexes.\n\n Parameters\n ----------\n deep : bool, default: True\n Whether the indexes are deep or shallow copied onto the new object.\n memo : dict if object id to copied objects or None, optional\n To prevent infinite recursion deepcopy stores all copied elements\n in this dict.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_07", "repo": "xarray", "question": "Where is the logic for stacking grouped arrays documented in `DataArrayResample`, and how does `apply` relate to `map`?", "category": "where", "sub_type": "feature_location", "gold_answer": "The `DataArrayResample.map` method uses heuristics (like `pandas.GroupBy.apply`) to determine how to stack together the arrays. The stacking rules are documented in the `map` method's docstring: (1) If the dimension along which the group coordinate is defined is still in the first grouped array after applying `func`, then stack over this dimension. (2) Otherwise, stack over the new dimension given by the name of this grouping (the argument to the `groupby` function). The `shortcut` parameter in `map` provides significant speedup when the action of `func` does not depend on array metadata and creates arrays with homogeneous metadata. The `apply` method is documented as a backward compatible implementation of `map`, indicating that `map` is the preferred/current method and `apply` exists for backward compatibility.", "rubric": [ "Explains that `map` uses heuristics (like `pandas.GroupBy.apply`) to determine how to stack arrays together", "Describes rule 1: if the group coordinate dimension is still in the first grouped array after applying func, stack over that dimension", "Describes rule 2: otherwise, stack over the new dimension given by the grouping name", "Mentions the `shortcut` parameter provides significant speedup when func doesn't depend on metadata and creates arrays with homogeneous metadata", "States that `apply` is a backward compatible implementation of `map` (i.e., `map` is the preferred method)" ], "key_files": [ "xarray/core/resample.py" ], "source_doc": "[docstring: xarray/core/resample.py] xarray.core.resample.DataArrayResample\nxarray.core.resample.DataArrayResample:\n DataArrayGroupBy object specialized to time resampling operations over a\n specified dimension\n\nxarray.core.resample.DataArrayResample.reduce:\n Reduce the items in this group by applying `func` along the\n pre-defined resampling dimension.\n\n Parameters\n ----------\n func : callable\n Function which can be called in the form\n `func(x, axis=axis, **kwargs)` to return the result of collapsing\n an np.ndarray over an integer valued axis.\n dim : \"...\", str, Iterable of Hashable or None, optional\n Dimension(s) over which to apply `func`.\n keep_attrs : bool, optional\n If True, the datasets's attributes (`attrs`) will be copied from\n the original object to the new one. If False (default), the new\n object will be returned without attributes.\n **kwargs : dict\n Additional keyword arguments passed on to `func`.\n\n Returns\n -------\n reduced : DataArray\n Array with summarized data and the indicated dimension(s)\n removed.\n\nxarray.core.resample.DataArrayResample.map:\n Apply a function to each array in the group and concatenate them\n together into a new array.\n\n `func` is called like `func(ar, *args, **kwargs)` for each array `ar`\n in this group.\n\n Apply uses heuristics (like `pandas.GroupBy.apply`) to figure out how\n to stack together the array. The rule is:\n\n 1. If the dimension along which the group coordinate is defined is\n still in the first grouped array after applying `func`, then stack\n over this dimension.\n 2. Otherwise, stack over the new dimension given by name of this\n grouping (the argument to the `groupby` function).\n\n Parameters\n ----------\n func : callable\n Callable to apply to each array.\n shortcut : bool, optional\n Whether or not to shortcut evaluation under the assumptions that:\n\n (1) The action of `func` does not depend on any of the array\n metadata (attributes or coordinates) but only on the data and\n dimensions.\n (2) The action of `func` creates arrays with homogeneous metadata,\n that is, with the same dimensions and attributes.\n\n If these conditions are satisfied `shortcut` provides significant\n speedup. This should be the case for many common groupby operations\n (e.g., applying numpy ufuncs).\n args : tuple, optional\n Positional arguments passed on to `func`.\n **kwargs\n Used to call `func(ar, **kwargs)` for each array `ar`.\n\n Returns\n -------\n applied : DataArray\n The result of splitting, applying and combining this array.\n\nxarray.core.resample.DataArrayResample.apply:\n Backward compatible implementation of ``map``\n\n See Also\n --------\n DataArrayResample.map\n\nxarray.core.resample.DataArrayResample.asfreq:\n Return values of original object at the new up-sampling frequency;\n essentially a re-index with new times set to NaN.\n\n Returns\n -------\n resampled : DataArray", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_06", "repo": "xarray", "question": "Why does xarray's `create_mask` function check whether the data is a dask or sparse array, and what conventions does it follow for marking masked positions?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The `create_mask` function in xarray's indexing module serves the purpose of creating a boolean mask for indexing operations that use a fill-value. The key design decisions documented are: (1) The convention that -1 values in integer or ndarray indexers indicate positions that should be masked in the result, (2) When the data being indexed is a dask array, the function uses the dask array's chunks as a hint for chunking the resulting mask, ensuring compatibility with lazy/parallel computation, and (3) When the data is a sparse array, the returned mask is also a sparse array, maintaining type consistency. The function is designed to return a mask of the same type as the input data (bool, np.ndarray, SparseArray, or dask.array.Array), always with dtype=bool, and shaped to match the indexing result rather than the original array shape.", "rubric": [ "Explains that -1 values in integer or ndarray indexers indicate positions that should be masked in the result", "Explains that when data is a dask array, its chunks are used as a hint for chunking the resulting mask to maintain compatibility with lazy/parallel computation", "Explains that when data is a sparse array, the mask is returned as a sparse array to maintain type consistency", "Notes that the function returns a mask with dtype=bool matching the type of the input data (bool, np.ndarray, SparseArray, or dask.array.Array)", "Notes that the mask shape matches the indexing result rather than the original array shape" ], "key_files": [ "xarray/core/indexing.py" ], "source_doc": "[docstring: xarray/core/indexing.py] xarray.core.indexing.create_mask\nCreate a mask for indexing with a fill-value.\n\n Parameters\n ----------\n indexer : ExplicitIndexer\n Indexer with -1 in integer or ndarray value to indicate locations in\n the result that should be masked.\n shape : tuple\n Shape of the array being indexed.\n data : optional\n Data for which mask is being created. If data is a dask arrays, its chunks\n are used as a hint for chunks on the resulting mask. If data is a sparse\n array, the returned mask is also a sparse array.\n\n Returns\n -------\n mask : bool, np.ndarray, SparseArray or dask.array.Array with dtype=bool\n Same type as data. Has the same shape as the indexing result.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_08", "repo": "xarray", "question": "How does `_get_time_bins` determine bin edges and labels for CFTimeIndex resampling, and what defaults does it use for `closed`, `label`, and `origin`?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "The `_get_time_bins` function determines bin intervals and labels for resampling CFTimeIndex data. The default behavior for `closed` and `label` parameters depends on the frequency offset type: for most frequency offsets, both `closed` and `label` default to 'left', but for 'M' (month-end) and 'A' (year-end) frequency offsets, both default to 'right'. The `origin` parameter defaults to 'start_day', which uses the first day at midnight of the timeseries as the reference point for adjusting grouping. Other origin options include 'epoch' (1970-01-01), 'start' (first value of the timeseries), 'end' (last value of the timeseries), and 'end_day' (ceiling midnight of the last day). An optional `offset` parameter (a timedelta) can be added to the origin to further adjust bin boundaries. The function returns two CFTimeIndex objects: `datetime_bins` which defines the edges of resampling bins for grouping, and `labels` which defines what the user actually sees the bins labeled as.", "rubric": [ "Explains that `closed` and `label` default to 'left' for most frequency offsets", "Explains that `closed` and `label` default to 'right' for MonthEnd, QuarterEnd, or YearEnd frequency offsets (or when origin is 'end'/'end_day')", "Explains that `origin` defaults to 'start_day', meaning the first day at midnight of the timeseries", "Lists or describes other origin options: 'epoch' (1970-01-01), 'start' (first value), 'end' (last value), 'end_day' (ceiling midnight of last day)", "Explains that an optional `offset` (timedelta) can be added to the origin to adjust bin boundaries", "Explains the function returns two CFTimeIndex objects: `datetime_bins` (bin edges for grouping) and `labels` (what users see bins labeled as)", "Mentions that labels are selected from left or right edges of bins depending on the `label` parameter" ], "key_files": [ "xarray/core/resample_cftime.py" ], "source_doc": "[docstring: xarray/core/resample_cftime.py] xarray.core.resample_cftime._get_time_bins\nObtain the bins and their respective labels for resampling operations.\n\n Parameters\n ----------\n index : CFTimeIndex\n Index object to be resampled (e.g., CFTimeIndex named 'time').\n freq : xarray.coding.cftime_offsets.BaseCFTimeOffset\n The offset object representing target conversion a.k.a. resampling\n frequency (e.g., 'MS', '2D', 'H', or '3T' with\n coding.cftime_offsets.to_offset() applied to it).\n closed : 'left' or 'right'\n Which side of bin interval is closed.\n The default is 'left' for all frequency offsets except for 'M' and 'A',\n which have a default of 'right'.\n label : 'left' or 'right'\n Which bin edge label to label bucket with.\n The default is 'left' for all frequency offsets except for 'M' and 'A',\n which have a default of 'right'.\n origin : {'epoch', 'start', 'start_day', 'end', 'end_day'} or cftime.datetime, default 'start_day'\n The datetime on which to adjust the grouping. The timezone of origin\n must match the timezone of the index.\n\n If a datetime is not used, these values are also supported:\n - 'epoch': `origin` is 1970-01-01\n - 'start': `origin` is the first value of the timeseries\n - 'start_day': `origin` is the first day at midnight of the timeseries\n - 'end': `origin` is the last value of the timeseries\n - 'end_day': `origin` is the ceiling midnight of the last day\n offset : datetime.timedelta, default is None\n An offset timedelta added to the origin.\n\n Returns\n -------\n datetime_bins : CFTimeIndex\n Defines the edge of resampling bins by which original index values will\n be grouped into.\n labels : CFTimeIndex\n Define what the user actually sees the bins labeled as.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_09", "repo": "xarray", "question": "What does the `origin` parameter in `_get_range_edges` control, and what are its valid string values and their meanings?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The `_get_range_edges` function in `xarray/core/resample_cftime.py` accepts an `origin` parameter that determines the datetime on which to adjust the grouping for resampling. The `origin` parameter defaults to `'start_day'`, and when string values are used, they have specific meanings: 'epoch' uses 1970-01-01 as the origin, 'start' uses the first value of the timeseries, 'start_day' uses the first day at midnight of the timeseries, 'end' uses the last value of the timeseries, and 'end_day' uses the ceiling midnight of the last day. The `first` parameter is described as the 'uncorrected' starting datetime, usually the min of the original CFTimeIndex, while the function returns a 'corrected' starting datetime. The `freq` parameter is of type `xarray.coding.cftime_offsets.BaseCFTimeOffset`, which contains information on both the offset type (e.g., Day or 'D') and the offset magnitude (e.g., n = 3). Additionally, the documentation specifies that when using a datetime as origin, its timezone must match the timezone of the index.", "rubric": [ "Explains that origin determines the datetime on which to adjust the grouping for resampling", "States that the default value is 'start_day'", "Mentions 'epoch' uses 1970-01-01 as the origin", "Mentions 'start' uses the first value of the timeseries", "Mentions 'start_day' uses the first day at midnight of the timeseries", "Mentions 'end' uses the last value of the timeseries", "Mentions 'end_day' uses the ceiling midnight of the last day", "Notes that origin can also be a cftime.datetime and its timezone must match the index's timezone", "Explains that `first` is the uncorrected starting datetime (usually the min of the original CFTimeIndex) and the function returns the corrected starting datetime", "Notes that `freq` is of type BaseCFTimeOffset containing offset type and magnitude information" ], "key_files": [ "xarray/core/resample_cftime.py" ], "source_doc": "[docstring: xarray/core/resample_cftime.py] xarray.core.resample_cftime._get_range_edges\nGet the correct starting and ending datetimes for the resampled\n CFTimeIndex range.\n\n Parameters\n ----------\n first : cftime.datetime\n Uncorrected starting datetime object for resampled CFTimeIndex range.\n Usually the min of the original CFTimeIndex.\n last : cftime.datetime\n Uncorrected ending datetime object for resampled CFTimeIndex range.\n Usually the max of the original CFTimeIndex.\n freq : xarray.coding.cftime_offsets.BaseCFTimeOffset\n The offset object representing target conversion a.k.a. resampling\n frequency. Contains information on offset type (e.g. Day or 'D') and\n offset magnitude (e.g., n = 3).\n closed : 'left' or 'right'\n Which side of bin interval is closed. Defaults to 'left'.\n origin : {'epoch', 'start', 'start_day', 'end', 'end_day'} or cftime.datetime, default 'start_day'\n The datetime on which to adjust the grouping. The timezone of origin\n must match the timezone of the index.\n\n If a datetime is not used, these values are also supported:\n - 'epoch': `origin` is 1970-01-01\n - 'start': `origin` is the first value of the timeseries\n - 'start_day': `origin` is the first day at midnight of the timeseries\n - 'end': `origin` is the last value of the timeseries\n - 'end_day': `origin` is the ceiling midnight of the last day\n offset : datetime.timedelta, default is None\n An offset timedelta added to the origin.\n\n Returns\n -------\n first : cftime.datetime\n Corrected starting datetime object for resampled CFTimeIndex range.\n last : cftime.datetime\n Corrected ending datetime object for resampled CFTimeIndex range.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "xarray_gen_10", "repo": "xarray", "question": "Why is `auto_convert` in `as_variable` kept as a deprecated internal-only parameter rather than being removed entirely?", "category": "why", "sub_type": "performance", "gold_answer": "The `auto_convert` parameter in `as_variable` is explicitly documented as being 'For internal use only!' and its behavior of converting a 'dimension' variable into an IndexVariable object is deprecated. This suggests a design decision where the conversion of dimension variables to IndexVariable was once a standard pattern, but the developers are moving away from it. The parameter is kept for backward compatibility with internal code that still relies on this behavior, but its deprecation signals that this automatic conversion pattern is being phased out in favor of a more explicit approach where the caller handles the distinction between regular Variables and IndexVariables. The 'why' behind keeping it as an internal-only deprecated parameter rather than removing it outright is to maintain backward compatibility during the transition period while discouraging any new external usage.", "rubric": [ "Explains that auto_convert converts a dimension variable (where name matches one of its dims) into an IndexVariable", "Notes that the parameter is marked as 'For internal use only' and its behavior is deprecated via a FutureWarning", "Explains the rationale of backward compatibility: internal code may still rely on this behavior during a transition period", "Recognizes that the deprecation signals a shift away from automatic conversion toward more explicit handling of Variable vs IndexVariable", "Mentions that keeping it temporarily allows a graceful transition while discouraging new external usage" ], "key_files": [ "xarray/core/variable.py" ], "source_doc": "[docstring: xarray/core/variable.py] xarray.core.variable.as_variable\nConvert an object into a Variable.\n\n Parameters\n ----------\n obj : object\n Object to convert into a Variable.\n\n - If the object is already a Variable, return a shallow copy.\n - Otherwise, if the object has 'dims' and 'data' attributes, convert\n it into a new Variable.\n - If all else fails, attempt to convert the object into a Variable by\n unpacking it into the arguments for creating a new Variable.\n name : str, optional\n If provided:\n\n - `obj` can be a 1D array, which is assumed to label coordinate values\n along a dimension of this given name.\n - Variables with name matching one of their dimensions are converted\n into `IndexVariable` objects.\n auto_convert : bool, optional\n For internal use only! If True, convert a \"dimension\" variable into\n an IndexVariable object (deprecated).\n\n Returns\n -------\n var : Variable\n The newly created variable.", "verification_verdict": "warn", "verification_issues": [ "The claim that 'the developers are moving away from it' is a plausible extrapolation from the deprecation notice but not explicitly stated in the documentation.", "The claim about 'maintaining backward compatibility during the transition period while discouraging any new external usage' is a reasonable inference but not directly supported by the documentation text.", "The claim about 'the caller handles the distinction between regular Variables and IndexVariables' as the new approach is speculative and not stated in the documentation.", "The explanation of 'why' behind keeping it as internal-only deprecated parameter is an interpretation/extrapolation, not something documented." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_03", "repo": "pylint", "question": "Where is the IOData class used in pylint's test suite and what do its two static methods do differently?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "The IOData class in the unspecified_encoding_py38.py test file is documented as a 'Class that returns mode strings'. It contains two methods: my_mode_method, which 'Returns a pre-defined mode', and my_mode_method_returner, which 'Returns the supplied mode'. This class is used in the functional test suite for pylint's unspecified_encoding checker, specifically for Python 3.8+ scenarios. The distinction between the two methods is that my_mode_method returns a pre-defined (hardcoded) mode string, while my_mode_method_returner acts as a pass-through that returns whatever mode is supplied to it. This design allows testing how pylint handles different patterns of mode string usage when checking for unspecified encoding in file operations.", "rubric": [ "IOData is located in the unspecified_encoding_py38 functional test file for pylint's unspecified-encoding checker", "IOData is documented as a 'Class that returns mode strings'", "my_mode_method returns a pre-defined/hardcoded mode string ('wb')", "my_mode_method_returner accepts a mode parameter and returns whatever mode is supplied to it (pass-through)", "The class is used to test how pylint handles different patterns of mode string usage (e.g., class attributes, instance attributes, method calls) when checking for unspecified encoding in open() calls" ], "key_files": [ "tests/functional/u/unspecified_encoding_py38.py" ], "source_doc": "[docstring: tests/functional/u/unspecified_encoding_py38.py] tests.functional.u.unspecified_encoding_py38.IOData\ntests.functional.u.unspecified_encoding_py38.IOData:\n Class that returns mode strings\n\ntests.functional.u.unspecified_encoding_py38.IOData.my_mode_method:\n Returns a pre-defined mode\n\ntests.functional.u.unspecified_encoding_py38.IOData.my_mode_method_returner:\n Returns the supplied mode", "verification_verdict": "warn", "verification_issues": [ "The claim that 'my_mode_method_returner acts as a pass-through that returns whatever mode is supplied to it' is a plausible extrapolation from 'Returns the supplied mode' but adds interpretation not explicitly stated in the documentation.", "The claim about 'testing how pylint handles different patterns of mode string usage when checking for unspecified encoding in file operations' is a reasonable inference from the file path context but is not explicitly stated in the documentation.", "The claim that this is 'specifically for Python 3.8+ scenarios' is inferred from the filename 'py38' but not explicitly stated in the documentation.", "The description of my_mode_method returning a 'hardcoded' mode string is an extrapolation of 'pre-defined mode' - plausible but adds specificity not in the docs." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_04", "repo": "pylint", "question": "How does the unused-private-member test for issue #4849 distinguish between private methods that should and shouldn't be flagged?", "category": "how", "sub_type": "system_design", "gold_answer": "In the FalsePositive4849 test class for pylint's unused-private-member checker, the system distinguishes between private methods based on their documentation-stated purpose: `__private_method` is documented as being 'private and does nothing' but is NOT flagged as unused because it is called by `use_private_method` (which 'Calls private method'). In contrast, `__unused_private_method` is documented as 'not used' and would be expected to trigger the unused-private-member warning. The test demonstrates how pylint's design handles the false positive case (issue #4849) where a private method that is actually called within the class should not be reported as unused, while a genuinely unused private method should still be flagged.", "rubric": [ "Mentions that `__private_method` is called by `use_private_method` via `cls.__private_method()` and therefore is NOT flagged", "Mentions that `__unused_private_method` is never called within the class and IS flagged with the unused-private-member warning", "Explains that the test demonstrates the false positive scenario where a private method actually used within the class should not be reported as unused", "Notes the use of @staticmethod for the private methods and @classmethod for the caller method" ], "key_files": [ "tests/functional/u/unused/unused_private_member.py" ], "source_doc": "[docstring: tests/functional/u/unused/unused_private_member.py] tests.functional.u.unused.unused_private_member.FalsePositive4849\ntests.functional.u.unused.unused_private_member.FalsePositive4849.__private_method:\n Is private and does nothing.\n\ntests.functional.u.unused.unused_private_member.FalsePositive4849.__unused_private_method:\n Is not used.\n\ntests.functional.u.unused.unused_private_member.FalsePositive4849.use_private_method:\n Calls private method.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_02", "repo": "pylint", "question": "Why doesn't pylint flag `bug_pylint_8747_incorrect_annotation` as having inconsistent returns when the called method's NoReturn annotation is clearly wrong?", "category": "why", "sub_type": "design_rationale", "gold_answer": "Pylint intentionally does not attempt to detect whether a NoReturn annotation is actually correct. If a function is annotated with NoReturn but actually does return a value, pylint will still treat it as consistent with other return paths. This is a deliberate design choice - pylint trusts the type annotations as given rather than performing deeper analysis to verify that a NoReturn-annotated function truly never returns. This means that in the case of `bug_pylint_8747_incorrect_annotation`, the returns are considered consistent by pylint even though the NoReturn annotation is factually wrong, because pylint relies on the declared type hint rather than analyzing the actual control flow of the annotated function.", "rubric": [ "Pylint intentionally trusts the declared type annotations rather than analyzing whether a NoReturn annotation is actually correct", "The _is_function_def_never_returning method only checks whether the function's return annotation name is 'NoReturn' or 'Never', without verifying actual control flow", "This is a deliberate design choice to rely on declared hints rather than performing deeper analysis of the annotated function's behavior", "As a result, calling a function falsely annotated as NoReturn is treated as a terminating call, making the return paths appear consistent" ], "key_files": [ "tests/functional/i/inconsistent/inconsistent_returns_noreturn.py" ], "source_doc": "[docstring: tests/functional/i/inconsistent/inconsistent_returns_noreturn.py] tests.functional.i.inconsistent.inconsistent_returns_noreturn.ClassUnderTest\ntests.functional.i.inconsistent.inconsistent_returns_noreturn.ClassUnderTest.bug_pylint_8747:\n Every return is consistent because self._no_return_method hints NoReturn\n\ntests.functional.i.inconsistent.inconsistent_returns_noreturn.ClassUnderTest.bug_pylint_8747_wrong:\n Every return is not consistent because self._does_return_method() returns a value\n\ntests.functional.i.inconsistent.inconsistent_returns_noreturn.ClassUnderTest.bug_pylint_8747_incorrect_annotation:\n Every return is consistent since pylint does not attempt to detect that the\n NoReturn annotation is incorrect and the function actually returns", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_01", "repo": "pylint", "question": "What is the mechanism for writing an AST transform plugin that teaches Pylint about dynamically-set class attributes?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The `register_transform` function in astroid's `MANAGER` is the mechanism used to register transform plugins. It takes two parameters: the node type to transform (e.g., `astroid.ClassDef` for class transformations) and a transform function that performs the actual transformation. In the transform function, you modify the class's `locals` dictionary to add attributes that Pylint can then see during analysis. The `register` function required by Pylint's plugin system does not need to do anything (can just `pass`) when the plugin is only performing AST transformations and not modifying the linter itself. The attribute types set in `locals` don't need to be precise \u2014 for example, setting them as `astroid.ClassDef` will work even if the actual attributes aren't classes, though you could set them to any type you want. Real-life examples of transform plugins can be found in the `astroid/brain` directory at https://github.com/pylint-dev/astroid/tree/main/astroid/brain.", "rubric": [ "Mentions using `MANAGER.register_transform` (or `astroid.MANAGER.register_transform`) to register the transform", "Explains that `register_transform` takes the node type (e.g., `astroid.ClassDef`) and a transform function as parameters", "Describes modifying the class's `locals` dictionary to add attributes that Pylint can then see", "Notes that the `register` function required by Pylint's plugin system can just `pass` when only doing AST transforms", "Mentions that attribute types in `locals` don't need to be precise (e.g., using `astroid.ClassDef` works even if they aren't actually classes)", "References `astroid/brain` as a source of real-life transform plugin examples" ], "key_files": [ "doc/development_guide/how_tos/transform_plugins.rst" ], "source_doc": "[doc_file: doc/development_guide/how_tos/transform_plugins.rst] Enter Plugin\nWe can write a transform plugin to tell Pylint how to analyze this properly.\n\nOne way to fix our example with a plugin would be to transform the ``WarningMessage`` class,\nby setting the attributes so that Pylint can see them. This can be done by\nregistering a transform function. We can transform any node in the parsed AST like\nModule, Class, Function etc. In our case we need to transform a class. It can be done so:\n\n.. sourcecode:: python\n\n from typing import TYPE_CHECKING\n\n import astroid\n\n if TYPE_CHECKING:\n from pylint.lint import PyLinter\n\n\n def register(linter: \"PyLinter\") -> None:\n \"\"\"This required method auto registers the checker during initialization.\n\n :param linter: The linter to register the checker to.\n \"\"\"\n pass\n\n def transform(cls):\n if cls.name == 'WarningMessage':\n import warnings\n for f in warnings.WarningMessage._WARNING_DETAILS:\n cls.locals[f] = [astroid.ClassDef(f, None)]\n\n astroid.MANAGER.register_transform(astroid.ClassDef, transform)\n\nLet's go through the plugin. First, we need to register a class transform, which\nis done via the ``register_transform`` function in ``MANAGER``. It takes the node\ntype and function as parameters. We need to change a class, so we use ``astroid.ClassDef``.\nWe also pass a ``transform`` function which does the actual transformation.\n\n``transform`` function is simple as well. If the class is ``WarningMessage`` then we\nadd the attributes to its locals (we are not bothered about type of attributes, so setting\nthem as class will do. But we could set them to any type we want). That's it.\n\nNote: We don't need to do anything in the ``register`` function of the plugin since we\nare not modifying anything in the linter itself.\n\nLets run Pylint with this plugin and see:\n\n.. sourcecode:: bash\n\n amitdev$ pylint -E --load-plugins warning_plugin Lib/warnings.py\n amitdev$\n\nAll the false positives associated with ``WarningMessage`` are now gone. This is just\nan example, any code transformation can be done by plugins.\n\nSee `astroid/brain`_ for real life examples of transform plugins.\n\n.. _`warnings.py`: https://hg.python.org/cpython/file/2.7/Lib/warnings.py\n.. _`astroid/brain`: https://github.com/pylint-dev/astroid/tree/main/astroid/brain", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_06", "repo": "pylint", "question": "Why was the `NamedTupleSubclass` test case added to the used-before-assignment tests, and what crash scenario does it guard against?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The `NamedTupleSubclass` test case in `used_before_assignment_py37.py` was created to address a specific bug reported in GitHub issue #5982 for the pylint-dev/pylint repository. The `method` within this class specifically tests a scenario where the variables checker would crash when astroid (pylint's AST framework) did not supply a line number (`lineno`). This test ensures that pylint's used-before-assignment check handles the edge case gracefully when AST nodes lack line number information, which can occur with certain Python 3.7+ constructs like NamedTuple subclasses.", "rubric": [ "Mentions it was created to address a specific bug (GitHub issue #5982)", "Explains that the variables checker crashed when astroid did not supply a line number (lineno)", "Notes this relates to NamedTuple subclasses where AST nodes may lack line number information", "Connects this to the used-before-assignment check handling edge cases gracefully" ], "key_files": [ "tests/functional/u/used/used_before_assignment_py37.py" ], "source_doc": "[docstring: tests/functional/u/used/used_before_assignment_py37.py] tests.functional.u.used.used_before_assignment_py37.NamedTupleSubclass\ntests.functional.u.used.used_before_assignment_py37.NamedTupleSubclass:\n Taken from https://github.com/pylint-dev/pylint/issues/5982\n\ntests.functional.u.used.used_before_assignment_py37.NamedTupleSubclass.method:\n Variables checker crashed when astroid did not supply a lineno", "verification_verdict": "warn", "verification_issues": [ "The claim that this 'ensures that pylint's used-before-assignment check handles the edge case gracefully' is a plausible extrapolation but not explicitly stated in the documentation.", "The claim that this 'can occur with certain Python 3.7+ constructs like NamedTuple subclasses' is a reasonable inference from the filename and class name but not explicitly stated in the documentation.", "The phrase 'This test ensures' implies it's a test that verifies correct behavior, which is a reasonable extrapolation but the documentation only says the checker 'crashed' - it doesn't explicitly say the test ensures graceful handling." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_05", "repo": "pylint", "question": "What scenario does `func_invalid3` test in the used-before-assignment except handler tests, and why is the nesting under `if` significant?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The test function `func_invalid3` in the used_before_assignment_except_handler_for_try_with_return tests represents a scenario where the variable 'msg' is not defined in one exception handler but is defined in another handler, with the definition nested under an `if` statement. This nesting specifically tests that the implementation does not incorrectly assume a direct parent-child relationship between the `msg=` assignment and the `except` block. Additionally, the prior except handler is necessary in this test because it is what raises the message (uses the 'msg' variable). The test validates that pylint correctly identifies the 'used before assignment' issue in this particular configuration of nested assignments within exception handlers.", "rubric": [ "Explains that 'msg' is not defined in one exception handler (AttributeError) but is defined in another (ZeroDivisionError)", "Notes that the assignment to 'msg' is nested under an `if` statement within the except block", "Explains that this nesting tests that the implementation does not incorrectly assume a direct parent-child relationship between the assignment and the except block", "Mentions that the prior except handler (AttributeError with pass) is necessary because it's what causes the used-before-assignment to be raised", "States that the test validates pylint correctly identifies 'used-before-assignment' in this nested configuration" ], "key_files": [ "tests/functional/u/used/used_before_assignment_except_handler_for_try_with_return.py" ], "source_doc": "[docstring: tests/functional/u/used/used_before_assignment_except_handler_for_try_with_return.py] tests.functional.u.used.used_before_assignment_except_handler_for_try_with_return.func_invalid3\n'msg' is not defined in one handler, but is defined in another\n nested under an if. Nesting under an if tests that the implementation\n does not assume direct parentage between `msg=` and `except`, and\n the prior except is necessary to raise the message.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_07", "repo": "pylint", "question": "Where is the --filter-mode option defined for pyreverse, and what modes does it support?", "category": "where", "sub_type": "feature_location", "gold_answer": "The --filter-mode option is located in pyreverse's configuration settings (documented at doc/additional_tools/pyreverse/configuration.rst). It controls filtering of attributes and functions in pyreverse output. The available modes are: 'PUB_ONLY' (default) which filters all non-public attributes and is equivalent to combining PRIVATE+SPECIAL filtering; 'ALL' which applies no filter; 'SPECIAL' which filters Python special functions except the constructor; and 'OTHER' which filters protected and private attributes.", "rubric": [ "Located in pylint/pyreverse/main.py within the OPTIONS tuple", "PUB_ONLY is the default mode, filtering all non-public attributes", "ALL mode applies no filter", "SPECIAL mode filters Python special functions except the constructor", "OTHER mode filters protected and private attributes", "PUB_ONLY is described as equivalent to PRIVATE+SPECIAL filtering" ], "key_files": [ "doc/additional_tools/pyreverse/configuration.rst" ], "source_doc": "[doc_file: doc/additional_tools/pyreverse/configuration.rst] --filter-mode\n*Filter attributes and functions according to . Correct modes are:\n'PUB_ONLY' filter all non public attributes [DEFAULT], equivalent to PRIVATE+SPECIAL\n'ALL' no filter\n'SPECIAL' filter Python special functions except constructor\n'OTHER' filter protected and private attributes*\n\n**Default:** ``PUB_ONLY``", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_08", "repo": "pylint", "question": "How does pyreverse's depth filtering algorithm calculate relative depth when multiple nested packages are specified?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "When using pyreverse's --max-depth option with nested packages, the depth calculation works as follows: A depth of 0 shows only the specified packages/modules themselves without any children. A depth of 1 includes the immediate children of the specified packages/modules. The key behavioral detail is that when specifying nested packages, depth is calculated relative to the deepest specified package level, not from the root or from each individual package. If the --max-depth option is not specified at all (default is None), all packages/modules in the hierarchy are shown without any depth limit. For example, if you specify packages 'a' and 'a.b.c', the depth would be calculated relative to 'a.b.c' (the deepest specified package), not relative to 'a'.", "rubric": [ "Depth 0 shows only the specified base packages themselves without children", "Depth 1 includes immediate children of the base packages", "When nested packages are specified (e.g., 'a' and 'a.b.c'), depth is calculated relative to the deepest/leaf package ('a.b.c'), not from the root or each individual package", "Non-leaf packages (those that are prefixes of other specified packages) are ignored for depth calculations, and a warning is emitted", "When max_depth is None (default), all nodes are included without any depth limit", "The depth of a node is computed as absolute_depth (dot count of node name) minus relative_depth (dot count of the matching leaf package)" ], "key_files": [ "doc/additional_tools/pyreverse/configuration.rst" ], "source_doc": "[doc_file: doc/additional_tools/pyreverse/configuration.rst] --max-depth\n*Maximum depth of packages/modules to include in the diagram, relative to the deepest specified package. A depth of 0 shows only the specified packages/modules, while 1 includes their immediate children, etc. When specifying nested packages, depth is calculated from the deepest package level. If not specified, all packages/modules in the hierarchy are shown.*\n\n**Default:** ``None``", "verification_verdict": "warn", "verification_issues": [ "The example about 'a' and 'a.b.c' is a plausible extrapolation but not explicitly stated in the documentation. The documentation says 'depth is calculated from the deepest package level' but doesn't give a concrete example like this. The interpretation that depth is relative to 'a.b.c' rather than 'a' is a reasonable reading but could also be interpreted differently - the doc says 'relative to the deepest specified package' which the answer correctly quotes, but the example is an embellishment.", "The answer says depth is calculated 'relative to the deepest specified package level, not from the root or from each individual package' - the 'not from the root or from each individual package' part is an extrapolation not explicitly in the docs, though it's a reasonable inference from the stated behavior." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_10", "repo": "pylint", "question": "Why does the `bad-super-call` checker allow explicit super calls with a non-direct parent class as the first argument?", "category": "why", "sub_type": "performance", "gold_answer": "The `bad-super-call` message exists primarily because of a historical design issue in Python 2.7, where `super()` required explicit class and self arguments (e.g., `super(Cat, self)`), which could lead to developers accidentally mixing up parent and child class names in the call. In Python 3, the recommended approach is to call `super()` without arguments, which eliminates this confusion. However, there is a documented exception: calling `super()` on a non-direct parent class is a legitimate pattern used to bypass the default method resolution order (MRO) and obtain a method from a specific ancestor class rather than the one that would normally be returned by `mro()`. This exception explains why pylint doesn't flag all explicit super calls with class arguments as errors\u2014some are intentional deviations from the MRO to achieve specific method resolution behavior.", "rubric": [ "Explains that calling super() on an ancestor (non-direct parent) is a legitimate pattern to skip steps in the MRO", "Mentions that this allows getting a method from a higher/specific parent rather than the one normally returned by mro()", "Notes the condition: the checker only flags calls where the class argument is neither the current class nor one of its ancestors", "Mentions or implies the historical context that in Python 2, super() required explicit arguments (class and self), making mix-ups likely" ], "key_files": [ "doc/data/messages/b/bad-super-call/details.rst" ], "source_doc": "[doc_file: doc/data/messages/b/bad-super-call/details.rst] (intro)\nIn Python 2.7, ``super()`` has to be called with its own class and ``self`` as arguments (``super(Cat, self)``), which can\nlead to a mix up of parent and child class in the code.\n\nIn Python 3 the recommended way is to call ``super()`` without arguments (see also ``super-with-arguments``).\n\nOne exception is calling ``super()`` on a non-direct parent class. This can be used to get a method other than the default\nmethod returned by the ``mro()``.", "verification_verdict": "warn", "verification_issues": [ "The claim 'This exception explains why pylint doesn't flag all explicit super calls with class arguments as errors\u2014some are intentional deviations from the MRO to achieve specific method resolution behavior' is a plausible extrapolation but not explicitly stated in the documentation. The doc only mentions the exception exists, not how pylint handles it specifically.", "The phrase 'bypass the default method resolution order' is a slight extrapolation - the doc says 'get a method other than the default method returned by the mro()' which is subtly different from bypassing the MRO entirely." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "pylint_gen_09", "repo": "pylint", "question": "What explains the discrepancy where the `anomalous-backslash-in-string` example raises `syntax-error` instead of the expected message?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "The `anomalous-backslash-in-string` message is demonstrated to raise `syntax-error` because pylint's CI now runs on Python 3.12, where using an invalid escape sequence like `\\z` truly raises a `SyntaxError`. In earlier Python versions, `\\z` was simply equivalent to `\\\\z` (i.e., the backslash is kept literally since there's no escape sequence for `z`), but this was unclear for code readers. The pylint team acknowledges this as a discrepancy in their documentation and hopes to address it in the future.", "rubric": [ "States that pylint's CI runs on Python 3.12 where invalid escape sequences like `\\z` truly raise a SyntaxError", "Explains that in earlier Python versions, `\\z` was equivalent to `\\\\z` (backslash kept literally since there's no escape sequence for `z`), but this is unclear for code readers", "Mentions that the pylint team acknowledges this as a documentation discrepancy they hope to address in the future" ], "key_files": [ "doc/data/messages/a/anomalous-backslash-in-string/details.rst" ], "source_doc": "[doc_file: doc/data/messages/a/anomalous-backslash-in-string/details.rst] (intro)\n``\\z`` is same as ``\\\\z`` because there's no escape sequence for ``z``. But it is not clear\nfor the reader of the code.\n\nThe only reason this is demonstrated to raise ``syntax-error`` is because\npylint's CI now runs on Python 3.12, where this truly raises a ``SyntaxError``.\nWe hope to address this discrepancy in the documentation in the future.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_03", "repo": "seaborn", "question": "Where does seaborn handle removal of null values from data vectors, and what are the input/output contracts of that helper?", "category": "where", "sub_type": "data_control_flow", "gold_answer": "The `remove_na` function in `seaborn/utils.py` is designed to work with any vector object that implements boolean masking with [] subscript syntax. The function returns cleaned data as the same type as the input vector, but importantly, the returned result may be either a copy or a view of the original data \u2014 this is explicitly documented as an implementation detail that callers should be aware of. The function serves as a helper method specifically for removing null values from data vectors, and its input requirement is that the vector must support boolean indexing via subscript notation.", "rubric": [ "Identifies the remove_na function in seaborn/utils.py as the location", "States the input must be a vector object that supports boolean masking with [] subscript syntax", "States the return type is the same type as the input vector", "Mentions the returned result may be either a copy or a view of the original data", "Notes the implementation uses pd.notnull for boolean indexing" ], "key_files": [ "seaborn/utils.py" ], "source_doc": "[docstring: seaborn/utils.py] seaborn.utils.remove_na\nHelper method for removing null values from data vectors.\n\n Parameters\n ----------\n vector : vector object\n Must implement boolean masking with [] subscript syntax.\n\n Returns\n -------\n clean_clean : same type as ``vector``\n Vector of data with null values removed. May be a copy or a view.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_04", "repo": "seaborn", "question": "How does `move_legend` actually reposition a legend, and why doesn't it simply change the location of the existing one?", "category": "how", "sub_type": "system_design", "gold_answer": "The `move_legend` function works by creating an entirely new legend rather than actually moving the existing one. This is because Matplotlib legends do not expose public control over their position parameters, making it impossible to simply reposition an existing legend. The function copies over the data from the original legend object into a new legend at the specified location, and then removes the original legend. Despite its name suggesting a simple repositioning operation, it is actually a recreation process \u2014 the documentation explicitly acknowledges this by stating 'The name is a slight misnomer.'", "rubric": [ "Explains that move_legend creates a new legend rather than moving the existing one", "Mentions that Matplotlib legends do not expose public control over their position parameters", "Describes that data (handles, labels, properties) is copied from the original legend to the new one", "Notes that the original legend is removed after the new one is created", "Acknowledges the function name is a misnomer since it recreates rather than repositions" ], "key_files": [ "seaborn/utils.py" ], "source_doc": "[docstring: seaborn/utils.py] seaborn.utils.move_legend\nRecreate a plot's legend at a new location.\n\n The name is a slight misnomer. Matplotlib legends do not expose public\n control over their position parameters. So this function creates a new legend,\n copying over the data from the original object, which is then removed.\n\n Parameters\n ----------\n obj : the object with the plot\n This argument can be either a seaborn or matplotlib object:\n\n - :class:`seaborn.FacetGrid` or :class:`seaborn.PairGrid`\n - :class:`matplotlib.axes.Axes` or :class:`matplotlib.figure.Figure`\n\n loc : str or int\n Location argument, as in :meth:`matplotlib.axes.Axes.legend`.\n\n kwargs\n Other keyword arguments are passed to :meth:`matplotlib.axes.Axes.legend`.\n\n Examples\n --------\n\n .. include:: ../docstrings/move_legend.rst", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_01", "repo": "seaborn", "question": "What does the `axes_style` function in seaborn do, and what are its available preset style options?", "category": "what", "sub_type": "architecture_exploration", "gold_answer": "The `axes_style` function in seaborn serves dual purposes: it retrieves the parameters that control the general style of plots, and it can also be used as a context manager to temporarily alter global defaults. The style parameters specifically control properties like the color of the background and whether a grid is enabled by default. This is accomplished using the matplotlib rcParams system. The available preconfigured style names are: darkgrid, whitegrid, dark, white, and ticks. For modifying global defaults permanently (for all plots), users should use `set_theme` or `set_style` instead. The `rc` parameter only updates parameters that are considered part of the style definition, meaning it won't override arbitrary rcParams \u2014 only those relevant to style.", "rubric": [ "Mentions that axes_style retrieves parameters controlling the general style of plots (e.g., background color, grid)", "Mentions it can be used as a context manager to temporarily alter global defaults", "Lists the available style names: darkgrid, whitegrid, dark, white, and ticks", "Mentions it uses the matplotlib rcParams system", "Notes that set_theme or set_style should be used instead to modify global defaults permanently", "Explains the rc parameter only updates parameters that are considered part of the style definition (filters to _style_keys)" ], "key_files": [ "seaborn/rcmod.py" ], "source_doc": "[docstring: seaborn/rcmod.py] seaborn.rcmod.axes_style\nGet the parameters that control the general style of the plots.\n\n The style parameters control properties like the color of the background and\n whether a grid is enabled by default. This is accomplished using the\n matplotlib rcParams system.\n\n The options are illustrated in the\n :doc:`aesthetics tutorial <../tutorial/aesthetics>`.\n\n This function can also be used as a context manager to temporarily\n alter the global defaults. See :func:`set_theme` or :func:`set_style`\n to modify the global defaults for all plots.\n\n Parameters\n ----------\n style : None, dict, or one of {darkgrid, whitegrid, dark, white, ticks}\n A dictionary of parameters or the name of a preconfigured style.\n rc : dict, optional\n Parameter mappings to override the values in the preset seaborn\n style dictionaries. This only updates parameters that are\n considered part of the style definition.\n\n Examples\n --------\n\n .. include:: ../docstrings/axes_style.rst", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_02", "repo": "seaborn", "question": "Why does seaborn's residplot include an optional lowess smoother on the residual scatterplot?", "category": "why", "sub_type": "design_rationale", "gold_answer": "The optional lowess smoother in seaborn's residplot function is provided as a diagnostic tool to help determine if there is structure to the residuals. The design rationale is that after regressing y on x and plotting the residuals as a scatterplot, a lowess smoother can reveal systematic patterns in the residuals that would indicate the linear model is not adequately capturing the relationship between the variables. This helps users assess model fit by visually detecting non-random patterns (such as curvature or heteroscedasticity) that might not be obvious from the raw scatter of residual points alone.", "rubric": [ "It serves as a diagnostic tool to detect structure or systematic patterns in the residuals", "It helps determine whether the linear model adequately captures the relationship between variables", "It can reveal non-random patterns (such as curvature) that might not be obvious from the raw scatter of points alone", "It assists in assessing model fit by highlighting when a linear regression is insufficient" ], "key_files": [ "seaborn/regression.py" ], "source_doc": "[docstring: seaborn/regression.py] seaborn.regression.residplot\nPlot the residuals of a linear regression.\n\n This function will regress y on x (possibly as a robust or polynomial\n regression) and then draw a scatterplot of the residuals. You can\n optionally fit a lowess smoother to the residual plot, which can\n help in determining if there is structure to the residuals.\n\n Parameters\n ----------\n data : DataFrame, optional\n DataFrame to use if `x` and `y` are column names.\n x : vector or string\n Data or column name in `data` for the predictor variable.\n y : vector or string\n Data or column name in `data` for the response variable.\n {x, y}_partial : vectors or string(s) , optional\n These variables are treated as confounding and are removed from\n the `x` or `y` variables before plotting.\n lowess : boolean, optional\n Fit a lowess smoother to the residual scatterplot.\n order : int, optional\n Order of the polynomial to fit when calculating the residuals.\n robust : boolean, optional\n Fit a robust linear regression when calculating the residuals.\n dropna : boolean, optional\n If True, ignore observations with missing data when fitting and\n plotting.\n label : string, optional\n Label that will be used in any plot legends.\n color : matplotlib color, optional\n Color to use for all elements of the plot.\n {scatter, line}_kws : dictionaries, optional\n Additional keyword arguments passed to scatter() and plot() for drawing\n the components of the plot.\n ax : matplotlib axis, optional\n Plot into this axis, otherwise grab the current axis or make a new\n one if not existing.\n\n Returns\n -------\n ax: matplotlib axes\n Axes with the regression plot.\n\n See Also\n --------\n regplot : Plot a simple linear regression model.\n jointplot : Draw a :func:`residplot` with univariate marginal distributions\n (when used with ``kind=\"resid\"``).\n\n Examples\n --------\n\n .. include:: ../docstrings/residplot.rst", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_06", "repo": "seaborn", "question": "Why does `choose_light_palette` exist as a widget, and why does its default color space input differ from `light_palette`?", "category": "why", "sub_type": "purpose_exploration", "gold_answer": "The `choose_light_palette` widget is designed for data that range between relatively uninteresting low values and interesting high values. This is the stated design rationale for why this kind of palette exists \u2014 it draws visual attention to the high end of the data range by using lighter/less saturated colors for low values and more vivid colors for high values. The documentation explicitly frames this as the intended use case, distinguishing it from other sequential palette types like dark_palette. Additionally, the documentation notes that the default color space input for this widget ('husl') is intentionally different from the default input for the `light_palette` function itself, though the specific reason for this divergence is not explained. The widget also requires IPython 2+ and must be used in the notebook environment.", "rubric": [ "It's designed for data ranging between relatively uninteresting low values and interesting high values", "The default input color space is 'husl' rather than the default used by the light_palette function itself", "The docstring acknowledges the difference in default input but does not explain the reason for the divergence", "It requires IPython 2+ and must be used in the notebook environment" ], "key_files": [ "seaborn/widgets.py" ], "source_doc": "[docstring: seaborn/widgets.py] seaborn.widgets.choose_light_palette\nLaunch an interactive widget to create a light sequential palette.\n\n This corresponds with the :func:`light_palette` function. This kind\n of palette is good for data that range between relatively uninteresting\n low values and interesting high values.\n\n Requires IPython 2+ and must be used in the notebook.\n\n Parameters\n ----------\n input : {'husl', 'hls', 'rgb'}\n Color space for defining the seed value. Note that the default is\n different than the default input for :func:`light_palette`.\n as_cmap : bool\n If True, the return value is a matplotlib colormap rather than a\n list of discrete colors.\n\n Returns\n -------\n pal or cmap : list of colors or matplotlib colormap\n Object that can be passed to plotting functions.\n\n See Also\n --------\n light_palette : Create a sequential palette with bright low values.\n dark_palette : Create a sequential palette with dark low values.\n cubehelix_palette : Create a sequential palette or colormap using the\n cubehelix system.", "verification_verdict": "warn", "verification_issues": [ "The answer claims the default color space input is 'husl' - while this is likely correct based on the parameter list showing 'husl' first in {'husl', 'hls', 'rgb'}, the documentation does not explicitly state that 'husl' is the default, only that 'the default is different than the default input for light_palette'.", "The answer states the palette uses 'lighter/less saturated colors for low values and more vivid colors for high values' - the documentation does not explicitly describe the mechanism this way. It only says the palette is good for data ranging between 'relatively uninteresting low values and interesting high values'. The See Also section says light_palette creates 'a sequential palette with bright low values', which suggests bright/light colors for low values, not necessarily 'less saturated'.", "The phrase 'draws visual attention to the high end of the data range' is a plausible extrapolation but not explicitly stated in the documentation." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_05", "repo": "seaborn", "question": "What is the `choose_dark_palette` widget, and how does its default input differ from `dark_palette`?", "category": "what", "sub_type": "concept_definition", "gold_answer": "The `choose_dark_palette` widget creates a dark sequential palette, which is described as being good for data that range between relatively uninteresting low values and interesting high values. It is an interactive widget counterpart to the `dark_palette` function, requires IPython 2+ and must be used in the notebook environment. Notably, the default color space input for this widget is different from the default input for the `dark_palette` function, though both accept 'husl', 'hls', and 'rgb' as color space options. The function can return either a list of discrete colors or a matplotlib colormap, depending on the `as_cmap` parameter.", "rubric": [ "Identifies choose_dark_palette as an interactive widget for creating a dark sequential palette", "Explains that it is good for data ranging between uninteresting low values and interesting high values", "Notes it requires IPython 2+ and must be used in the notebook", "States that choose_dark_palette defaults to 'husl' input while dark_palette defaults to 'rgb'", "Mentions that both accept 'husl', 'hls', and 'rgb' as color space options", "Notes the function can return either a list of discrete colors or a matplotlib colormap depending on the as_cmap parameter" ], "key_files": [ "seaborn/widgets.py" ], "source_doc": "[docstring: seaborn/widgets.py] seaborn.widgets.choose_dark_palette\nLaunch an interactive widget to create a dark sequential palette.\n\n This corresponds with the :func:`dark_palette` function. This kind\n of palette is good for data that range between relatively uninteresting\n low values and interesting high values.\n\n Requires IPython 2+ and must be used in the notebook.\n\n Parameters\n ----------\n input : {'husl', 'hls', 'rgb'}\n Color space for defining the seed value. Note that the default is\n different than the default input for :func:`dark_palette`.\n as_cmap : bool\n If True, the return value is a matplotlib colormap rather than a\n list of discrete colors.\n\n Returns\n -------\n pal or cmap : list of colors or matplotlib colormap\n Object that can be passed to plotting functions.\n\n See Also\n --------\n dark_palette : Create a sequential palette with dark low values.\n light_palette : Create a sequential palette with bright low values.\n cubehelix_palette : Create a sequential palette or colormap using the\n cubehelix system.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_07", "repo": "seaborn", "question": "Where is the default configuration for Plot instances defined, and how is it accessed \u2014 as a class-level or instance-level attribute?", "category": "where", "sub_type": "feature_location", "gold_answer": "The Plot object's default behavior is configured through the `Plot.config` attribute, which is accessed as a property of the class itself (e.g., `Plot.config`), not as a method called on a specific instance of the Plot object. This means configuration is done at the class level rather than per-instance, and users should interact with it via the class directly (e.g., `Plot.config`) rather than on an instantiated plot object.", "rubric": [ "The config attribute is defined as a class-level attribute on the Plot class (Plot.config = PlotConfig())", "It is an instance of PlotConfig, assigned directly on the class rather than in __init__", "Users access it via Plot.config (on the class itself), not on a specific Plot instance", "This means configuration applies globally to all Plot instances rather than per-instance" ], "key_files": [ "doc/_templates/autosummary/plot.rst" ], "source_doc": "[doc_file: doc/_templates/autosummary/plot.rst] Configuration\nThe :class:`Plot` object's default behavior can be configured through its :attr:`Plot.config` attribute. Notice that this is a property of the class, not a method on an instance.\n\n.. include:: ../docstrings/objects.Plot.config.rst", "verification_verdict": "warn", "verification_issues": [ "The documentation says Plot.config is 'a property of the class, not a method on an instance.' The answer interprets this as meaning configuration is done at the class level rather than per-instance. While this is a plausible interpretation, the documentation specifically says it's not a 'method' on an instance \u2014 it doesn't explicitly say it can't be accessed on an instance at all. The answer's claim that 'users should interact with it via the class directly rather than on an instantiated plot object' is an extrapolation that goes slightly beyond what the documentation explicitly states." ], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_08", "repo": "seaborn", "question": "How should you replicate the old `regplot` behavior with marginal distributions, and how do `regplot`, `lmplot`, and `jointplot` relate after the v0.3 API change?", "category": "how", "sub_type": "algorithm_implementation", "gold_answer": "To get the old multi-component plot behavior that `regplot` used to produce (with distributions in marginal axes), you should use `jointplot` with `kind=\"reg\"`. In the v0.3.0 API change, `regplot` was redesigned to be an 'Axes-level' function that can be plotted into any existing figure on a specific set of axes. The old `regplot` produced a multi-component plot with distributions in marginal axes, but this was moved to `jointplot(kind='reg')`. Additionally, `lmplot` now uses `regplot` behind the scenes, so all regression model fitting and representation options are shared between both functions. The `lmplot` function was rewritten to exploit `FacetGrid` machinery and now returns the `FacetGrid` instance used to draw the plot. The `color` keyword argument in `lmplot` was replaced with `hue` for consistency \u2014 `hue` always takes a variable *name*, while `color` takes a color name or palette.", "rubric": [ "To get old regplot behavior with marginal distributions, use jointplot with kind='reg'", "regplot became an Axes-level function that can be plotted into any existing figure on a specific set of axes", "lmplot uses regplot behind the scenes (calls regplot via map_dataframe), sharing all regression model fitting options", "lmplot was rewritten to exploit FacetGrid machinery and returns the FacetGrid instance", "The color keyword argument in lmplot was replaced with hue for consistency \u2014 hue takes a variable name while color takes a color name or palette" ], "key_files": [ "doc/whatsnew/v0.3.0.rst" ], "source_doc": "[doc_file: doc/whatsnew/v0.3.0.rst] API changes\n- The most noticeable change will be that :func:`regplot` no longer produces a multi-component plot with distributions in marginal axes. Instead. :func:`regplot` is now an \"Axes-level\" function that can be plotted into any existing figure on a specific set of axes. :func:`regplot` and :func:`lmplot` have also been unified (the latter uses the former behind the scenes), so all options for how to fit and represent the regression model can be used for both functions. To get the old behavior of :func:`regplot`, use :func:`jointplot` with ``kind=\"reg\"``.\n\n- As noted above, :func:`lmplot` has been rewritten to exploit the :class:`FacetGrid` machinery. This involves a few changes. The ``color`` keyword argument has been replaced with ``hue``, for better consistency across the package. The ``hue`` parameter will always take a variable *name*, while ``color`` will take a color name or (in some cases) a palette. The :func:`lmplot` function now returns the :class:`FacetGrid` used to draw the plot instance.\n\n- The functions that interact with matplotlib rc parameters have been updated and standardized. There are now three pairs of functions, :func:`axes_style` and :func:`set_style`, :func:`plotting_context` and :func:`set_context`, and :func:`color_palette` and :func:`set_palette`. In each case, the pairs take the exact same arguments. The first function defines and returns the parameters, and the second sets the matplotlib defaults. Additionally, the first function in each pair can be used in a ``with`` statement to temporarily change the defaults. Both the style and context functions also now accept a dictionary of matplotlib rc parameters to override the seaborn defaults, and :func:`set` now also takes a dictionary to update any of the matplotlib defaults. See the :ref:`tutorial ` for more information.\n\n- The ``nogrid`` style has been deprecated and changed to ``white`` for more uniformity (i.e. there are now ``darkgrid``, ``dark``, ``whitegrid``, and ``white`` styles).", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_10", "repo": "seaborn", "question": "Why does `reset_orig` restore rcParams from a snapshot taken at import time instead of using matplotlib's built-in defaults?", "category": "why", "sub_type": "performance", "gold_answer": "The `reset_orig` function (and importing `seaborn.apionly`) was designed to reset matplotlib rcParams to their values at the time seaborn itself was imported, rather than resetting to matplotlib's absolute defaults. This design choice was made specifically to work better with rcParams that have been changed by the Jupyter notebook backend. The rationale is that by the time seaborn is imported in a Jupyter notebook, the notebook backend may have already modified certain rcParams, and resetting to those values (rather than matplotlib's original defaults) preserves the notebook's expected behavior and visual output. This is a performance/compatibility consideration where the 'snapshot' approach ensures the interactive notebook environment continues to function correctly after a reset.", "rubric": [ "Explains that `_orig_rc_params` is captured via `mpl.rcParams.copy()` at seaborn import time, creating a snapshot of the current state", "Mentions that this preserves any rcParams modifications already made by the Jupyter/IPython notebook backend before seaborn was imported", "Contrasts this with `reset_defaults` which uses `mpl.rcParamsDefault` (matplotlib's absolute/built-in defaults)", "Notes the compatibility rationale: resetting to the import-time snapshot ensures the notebook environment continues to function correctly after a reset" ], "key_files": [ "doc/whatsnew/v0.7.1.rst" ], "source_doc": "[doc_file: doc/whatsnew/v0.7.1.rst] v0.7.1 (June 2016)\n- Added the ability to put \"caps\" on the error bars that are drawn by :func:`barplot` or :func:`pointplot` (and, by extension, ``factorplot``). Additionally, the line width of the error bars can now be controlled. These changes involve the new parameters ``capsize`` and ``errwidth``. See the `github pull request (#898) `_ for examples of usage.\n\n- Improved the row and column colors display in :func:`clustermap`. It is now possible to pass Pandas objects for these elements and, when possible, the semantic information in the Pandas objects will be used to add labels to the plot. When Pandas objects are used, the color data is matched against the main heatmap based on the index, not on position. This is more accurate, but it may lead to different results if current code assumed positional matching.\n\n- Improved the luminance calculation that determines the annotation color in :func:`heatmap`.\n\n- The ``annot`` parameter of :func:`heatmap` now accepts a rectangular dataset in addition to a boolean value. If a dataset is passed, its values will be used for the annotations, while the main dataset will be used for the heatmap cell colors.\n\n- Fixed a bug in :class:`FacetGrid` that appeared when using ``col_wrap`` with missing ``col`` levels.\n\n- Made it possible to pass a tick locator object to the :func:`heatmap` colorbar.\n\n- Made it possible to use different styles (e.g., step) for :class:`PairGrid` histograms when there are multiple hue levels.\n\n- Fixed a bug in scipy-based univariate kernel density bandwidth calculation.\n\n- The :func:`reset_orig` function (and, by extension, importing ``seaborn.apionly``) resets matplotlib rcParams to their values at the time seaborn itself was imported, which should work better with rcParams changed by the jupyter notebook backend.\n\n- Removed some objects from the top-level ``seaborn`` namespace.\n\n- Improved unicode compatibility in :class:`FacetGrid`.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null }, { "id": "seaborn_gen_09", "repo": "seaborn", "question": "What are seaborn's core required dependencies, and what does the `reset_orig` function do in relation to the `apionly` import approach?", "category": "what", "sub_type": "dependency_tracing", "gold_answer": "In seaborn v0.3.0, the minimum required dependencies were reduced to only numpy, scipy, matplotlib, and pandas. While statsmodels is still recommended for full functionality, it is not required. This means the package can be installed and used with just those four core dependencies. The `seaborn.apionly` module was introduced to allow users to access seaborn's plotting functions without automatically setting the matplotlib style to a seaborn theme. This module works by using the new `reset_orig` function, which returns rc parameters to what they are at matplotlib import time \u2014 meaning it will respect any custom matplotlibrc settings on top of the matplotlib defaults.", "rubric": [ "Identifies the core dependencies as numpy, pandas, and matplotlib (with scipy being optional in current code or required in v0.3.0)", "Mentions that statsmodels is optional/not required for basic functionality (listed under optional 'stats' dependencies)", "Explains that reset_orig restores matplotlib rcParams to their original state at import time (using _orig_rc_params captured at init)", "Explains that the apionly module allowed importing seaborn without applying the seaborn theme/style to matplotlib", "Notes that reset_orig respects custom matplotlibrc settings because it captures rcParams at matplotlib import time rather than using rcParamsDefault" ], "key_files": [ "doc/whatsnew/v0.3.0.rst" ], "source_doc": "[doc_file: doc/whatsnew/v0.3.0.rst] Using the package\n- If you want to use plotting functions provided by the package without setting the matplotlib style to a seaborn theme, you can now do ``import seaborn.apionly as sns`` or ``from seaborn.apionly import lmplot``, etc. This is using the (also new) :func:`reset_orig` function, which returns the rc parameters to what they are at matplotlib import time \u2014 i.e. they will respect any custom `matplotlibrc` settings on top of the matplotlib defaults.\n\n- The dependency load of the package has been reduced. It can now be installed and used with only ``numpy``, ``scipy``, ``matplotlib``, and ``pandas``. Although ``statsmodels`` is still recommended for full functionality, it is not required.", "verification_verdict": "pass", "verification_issues": [], "strip_verify_leakage": null, "strip_verify_summary": null, "generation_status": "completed", "generation_error": null } ]