> For the complete documentation index, see [llms.txt](https://www.csvpath.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.csvpath.org/topics/higher-level-topics/data-validation-files-and-storage/named_files_and_paths.md). # Named Files and Paths `CsvPaths` instances work with named-files, named-paths, and named-results. What are those? * A named-file is simply a name that points to a physical file location * A named-paths name points to a set of csvpaths that run together as a unit * Named-results are the results of running a set of named-paths; their names are the same ## Named Files Named-files are a convenience. It's a lot easier to ask `CsvPaths` to process orders with their validations like this: ```python lines = csvpaths.collect_paths(filename=august_orders, pathsname=orders_validation) ``` Rather than, potentially, something like: ```python lines = csvpaths.collect_paths( filename=/users/me/validation/orders/august/aug-31-2024.csv, pathsname=....what do I even enter here? ``` {% hint style="warning" %} The latter is an illustration, not a real method call. {% endhint %} `CsvPaths`'s file manager also takes care of caching and other background details that `CsvPath` instances on their own don't support. ## Named Files Named-paths are more interesting. The goal with named-paths is for us to be able to easily run multiple csvpaths against a single file in one go. The attraction to that is primarily that you can segment your validations into separate and composable csvpaths. As discussed in [Validation Strategies](/topics/higher-level-topics/validation/validation_strategies.md) and [Another Example, Part 2](/topics/how-tos/a-longer-example/another-example-part-2.md), separate cvpaths can be important to: * Quality control of your validation * Maintainability * Reuse and efficient development * Performance You can set up named-paths that are simple 1-to-1 names, like with named-files. But you can also have multiple csvpaths in one file or multiple files keyed by one named-paths name. The options are: * Put your csvpath files in a directory and import them under whatever name you like * Put your csvpath files in a directory and import them, each as separate named-path, optionally with multiple csvpaths per file * Read a JSON structure from a file that contains a `Dict[str, List[str]]` where the list of strings is a list of csvpaths * Do the same, but constructing the `Dict[str, List[str]]` yourself in Python There is a table of the advantages of each approach [here](/topics/how-tos/a-longer-example/another-example-part-2.md). Keep in mind that order matters in CsvPath. The order of match components within a csvpath is most important. But the order csvpaths are run in may also have an impact. Depending on if you run your named-paths breadth-first (a.k.a. line-by-line) or serially, you can enable different interactions. The differences are [discussed here](/topics/practical-stuff/serial-or-breadth-first-runs.md). Having your separate csvpaths impact one another is optional, of course! It is important to remember that order is important across csvpaths as well as within a single csvpath because when you import csvpaths from a directory the order is not guaranteed. By contrast, the order of csvpaths within single file is clear. Likewise, the order in the `Dict[str, List[str]]` structure is deterministic. ## Named Results `CsvPaths` instances keep named-results in [an archive](/topics/practical-stuff/namespacing-with-the-archive.md) that stores the outputs from named-paths runs. The name of the results is the same as the name of the paths that generated them. Named results are a collection of one `Result` object per `CsvPath` instance per csvpath string. The `Result` objects hold: * The `CsvPath` instance that ran each csvpath in the named-paths set * All the print output lines * The CSV file lines that matched the csvpath *(optionally)* * Any errors that happened *(configurable in* [*config.ini*](/topics/how-tos/config.ini.md)*)* The CsvPath instance also holds the metadata and variables collections. All-in-all, named-results have a ton of data to support your validations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.csvpath.org/topics/higher-level-topics/data-validation-files-and-storage/named_files_and_paths.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.