csv.register_dialect

A module-wide dict from names to validated dialects. register_dialect adds or replaces a name, get_dialect looks one up, list_dialects lists them in registration order, unregister_dialect removes one.

csv functionPython 2.3+Live demo
Common call
csv.register_dialect('pipes', delimiter='|')
Returns
None — then csv.reader(f, dialect='pipes')
Replaces
passing the same keyword arguments everywhere
Watch out
the registry is global to the process; an unknown name is csv.Error
csv.register_dialect(namename — The name to register (must be a str).type: str · required, dialectdialect — A Dialect class/instance or another registered name to start from; None starts from the excel defaults.type: str | Dialect · default: None=None, **fmtparams**fmtparams — delimiter=, quotechar=, quoting= … applied on top. Validated immediately.type: keyword arguments · default: null)
→ None

Demo

Live evaluation
Register a name with a delimiter, list the names, read the delimiter back — then unregister it again.
Try:
Inputs
namestrdialect name
delimiterstrone character
Code
import csv
csv.register_dialect('pipes', delimiter='|')
try:
    result = (csv.list_dialects(), csv.get_dialect('pipes').delimiter)
finally:
    csv.unregister_dialect('pipes')
result
Result
(['excel', 'excel-tab', 'unix', 'pipes'], '|')

New names are added after the three built-in ones (registration order). The settings are validated when you register, so an empty delimiter fails right there with TypeError: "delimiter" must be a 1-character string — and nothing is registered. get_dialect returns the validated _csv.Dialect; an unknown name raises csv.Error: unknown dialect (shown as _csv.Error).

Parameters

NameTypeRequiredDescription
namestryesThe name to register (must be a str).
dialectstr | Dialectno (None)A Dialect class/instance or another registered name to start from; None starts from the excel defaults.
fmtparamskeyword argumentsnodelimiter=, quotechar=, quoting= … applied on top. Validated immediately.

Return value

None — register_dialect and unregister_dialect return None; get_dialect returns a _csv.Dialect; list_dialects a list of names.

Common patterns

Register once, use by name
Typically at import time of your module.
import csv
csv.register_dialect('pipes', delimiter='|', quoting=csv.QUOTE_MINIMAL)

with open('data.psv', newline='', encoding='utf-8') as f:
    rows = list(csv.reader(f, dialect='pipes'))
Register a dialect class
Pass a csv.Dialect subclass as the second argument.
import csv

class Pipes(csv.excel):
    delimiter = '|'

csv.register_dialect('pipes', Pipes)
Register only if missing
list_dialects() returns the current names.
import csv
if 'pipes' not in csv.list_dialects():
    csv.register_dialect('pipes', delimiter='|')

Examples

1. The built-in names
import csv csv.list_dialects()
Returns
['excel', 'excel-tab', 'unix']
2. Register and use
import csv csv.register_dialect('pipes', delimiter='|') try: row = next(csv.reader(['a|b'], dialect='pipes')) finally: csv.unregister_dialect('pipes') row
Returns
['a', 'b']
3. Start from another dialect
import csv csv.register_dialect('tabq', 'excel-tab', quoting=csv.QUOTE_ALL) try: d = csv.get_dialect('tabq') info = (d.delimiter, d.quoting) finally: csv.unregister_dialect('tabq') info
Returns
('\t', 1)
4. get_dialect returns _csv.Dialect
import csv type(csv.get_dialect('excel'))
Returns
<class '_csv.Dialect'>
5. Unknown names
import csv csv.get_dialect('tsv')
Returns
_csv.Error: unknown dialect
6. Unregister an unknown name
import csv csv.unregister_dialect('tsv')
Returns
_csv.Error: unknown dialect
7. Names must be strings
import csv csv.register_dialect(1, delimiter=';')
Returns
TypeError: dialect name must be a string

Pitfalls

1. Changing the class after registering
register_dialect validates and copies the settings into a _csv.Dialect at that moment; later changes to the class are not seen.
edit the class
import csv
class Pipes(csv.excel):
    delimiter = '|'
csv.register_dialect('pipes', Pipes)
try:
    Pipes.delimiter = ';'
    d = csv.get_dialect('pipes').delimiter
finally:
    csv.unregister_dialect('pipes')
d
'|'
register again
import csv
class Pipes(csv.excel):
    delimiter = '|'
csv.register_dialect('pipes', Pipes)
try:
    Pipes.delimiter = ';'
    csv.register_dialect('pipes', Pipes)
    d = csv.get_dialect('pipes').delimiter
finally:
    csv.unregister_dialect('pipes')
d
';'
2. Misspelling a name
The error only says unknown dialect — compare with list_dialects(). The tab dialect is 'excel-tab' with a hyphen.
'excel_tab'
import csv
csv.reader([], dialect='excel_tab')
_csv.Error: unknown dialect
'excel-tab'
import csv
csv.reader([], dialect='excel-tab').dialect.delimiter
'\t'

When to use

Use it
  • A custom format used across a code base by name
  • Configuration that names a format as a string
Reach for something else
  • Library code: the registry is global — pass a Dialect class instead of registering names others might clash with

Notes

CPython impl
Modules/_csv.c — the registry is a dict in the module state (also visible as _csv._dialects); register_dialect stores _csv.Dialect(dialect, **fmtparams); list_dialects returns list(dict.keys())
Errors
get_dialect / unregister_dialect: csv.Error("unknown dialect"); register_dialect with a non-str name: TypeError
Overwriting
Registering an existing name replaces it silently — even excel

FAQ

csv.list_dialects() — ['excel', 'excel-tab', 'unix'] plus any names registered in the running program.