csv — CSV File Reading and Writing — Python 3.10.7 ...

The csv module implements classes to read and write tabular data in CSV format. ... The Python Enhancement Proposal which proposed this addition to Python. Navigation index modules| next| previous| Python» 3.10.7Documentation» ThePythonStandardLibrary» FileFormats» csv—CSVFileReadingandWriting | csv—CSVFileReadingandWriting¶ Sourcecode:Lib/csv.py Theso-calledCSV(CommaSeparatedValues)formatisthemostcommonimportand exportformatforspreadsheetsanddatabases.CSVformatwasusedformany yearspriortoattemptstodescribetheformatinastandardizedwayin RFC4180.Thelackofawell-definedstandardmeansthatsubtledifferences oftenexistinthedataproducedandconsumedbydifferentapplications.These differencescanmakeitannoyingtoprocessCSVfilesfrommultiplesources. Still,whilethedelimitersandquotingcharactersvary,theoverallformatis similarenoughthatitispossibletowriteasinglemodulewhichcan efficientlymanipulatesuchdata,hidingthedetailsofreadingandwritingthe datafromtheprogrammer. ThecsvmoduleimplementsclassestoreadandwritetabulardatainCSV format.Itallowsprogrammerstosay,“writethisdataintheformatpreferred byExcel,”or“readdatafromthisfilewhichwasgeneratedbyExcel,”without knowingtheprecisedetailsoftheCSVformatusedbyExcel.Programmerscan alsodescribetheCSVformatsunderstoodbyotherapplicationsordefinetheir ownspecial-purposeCSVformats. Thecsvmodule’sreaderandwriterobjectsreadand writesequences.Programmerscanalsoreadandwritedataindictionaryform usingtheDictReaderandDictWriterclasses. Seealso PEP305-CSVFileAPIThePythonEnhancementProposalwhichproposedthisadditiontoPython. ModuleContents¶ Thecsvmoduledefinesthefollowingfunctions: csv.reader(csvfile,dialect='excel',**fmtparams)¶ Returnareaderobjectwhichwilliterateoverlinesinthegivencsvfile. csvfilecanbeanyobjectwhichsupportstheiteratorprotocolandreturnsa stringeachtimeits__next__()methodiscalled—fileobjectsandlistobjectsarebothsuitable.Ifcsvfileisafileobject, itshouldbeopenedwithnewline=''.1Anoptional dialectparametercanbegivenwhichisusedtodefineasetofparameters specifictoaparticularCSVdialect.Itmaybeaninstanceofasubclassof theDialectclassoroneofthestringsreturnedbythe list_dialects()function.Theotheroptionalfmtparamskeywordarguments canbegiventooverrideindividualformattingparametersinthecurrent dialect.Forfulldetailsaboutthedialectandformattingparameters,see sectionDialectsandFormattingParameters. Eachrowreadfromthecsvfileisreturnedasalistofstrings.No automaticdatatypeconversionisperformedunlesstheQUOTE_NONNUMERICformat optionisspecified(inwhichcaseunquotedfieldsaretransformedintofloats). Ashortusageexample: >>>importcsv >>>withopen('eggs.csv',newline='')ascsvfile: ...spamreader=csv.reader(csvfile,delimiter='',quotechar='|') ...forrowinspamreader: ...print(','.join(row)) Spam,Spam,Spam,Spam,Spam,BakedBeans Spam,LovelySpam,WonderfulSpam csv.writer(csvfile,dialect='excel',**fmtparams)¶ Returnawriterobjectresponsibleforconvertingtheuser’sdataintodelimited stringsonthegivenfile-likeobject.csvfilecanbeanyobjectwitha write()method.Ifcsvfileisafileobject,itshouldbeopenedwith newline=''1.Anoptionaldialect parametercanbegivenwhichisusedtodefineasetofparametersspecifictoa particularCSVdialect.Itmaybeaninstanceofasubclassofthe Dialectclassoroneofthestringsreturnedbythe list_dialects()function.Theotheroptionalfmtparamskeywordarguments canbegiventooverrideindividualformattingparametersinthecurrent dialect.Forfulldetailsaboutdialectsandformattingparameters,see theDialectsandFormattingParameterssection.Tomakeit aseasyaspossibletointerfacewithmoduleswhichimplementtheDBAPI,the valueNoneiswrittenastheemptystring.Whilethisisn’ta reversibletransformation,itmakesiteasiertodumpSQLNULLdatavaluesto CSVfileswithoutpreprocessingthedatareturnedfromacursor.fetch*call. Allothernon-stringdataarestringifiedwithstr()beforebeingwritten. Ashortusageexample: importcsv withopen('eggs.csv','w',newline='')ascsvfile: spamwriter=csv.writer(csvfile,delimiter='', quotechar='|',quoting=csv.QUOTE_MINIMAL) spamwriter.writerow(['Spam']*5+['BakedBeans']) spamwriter.writerow(['Spam','LovelySpam','WonderfulSpam']) csv.register_dialect(name[,dialect[,**fmtparams]])¶ Associatedialectwithname.namemustbeastring.The dialectcanbespecifiedeitherbypassingasub-classofDialect,or byfmtparamskeywordarguments,orboth,withkeywordargumentsoverriding parametersofthedialect.Forfulldetailsaboutdialectsandformatting parameters,seesectionDialectsandFormattingParameters. csv.unregister_dialect(name)¶ Deletethedialectassociatedwithnamefromthedialectregistry.An Errorisraisedifnameisnotaregistereddialectname. csv.get_dialect(name)¶ Returnthedialectassociatedwithname.AnErrorisraisedif nameisnotaregistereddialectname.Thisfunctionreturnsanimmutable Dialect. csv.list_dialects()¶ Returnthenamesofallregistereddialects. csv.field_size_limit([new_limit])¶ Returnsthecurrentmaximumfieldsizeallowedbytheparser.Ifnew_limitis given,thisbecomesthenewlimit. Thecsvmoduledefinesthefollowingclasses: classcsv.DictReader(f,fieldnames=None,restkey=None,restval=None,dialect='excel',*args,**kwds)¶ Createanobjectthatoperateslikearegularreaderbutmapsthe informationineachrowtoadictwhosekeysaregivenbythe optionalfieldnamesparameter. Thefieldnamesparameterisasequence.Iffieldnamesis omitted,thevaluesinthefirstrowoffilefwillbeusedasthe fieldnames.Regardlessofhowthefieldnamesaredetermined,the dictionarypreservestheiroriginalordering. Ifarowhasmorefieldsthanfieldnames,theremainingdataisputina listandstoredwiththefieldnamespecifiedbyrestkey(whichdefaults toNone).Ifanon-blankrowhasfewerfieldsthanfieldnames,the missingvaluesarefilled-inwiththevalueofrestval(whichdefaults toNone). Allotheroptionalorkeywordargumentsarepassedtotheunderlying readerinstance. Changedinversion3.6:ReturnedrowsarenowoftypeOrderedDict. Changedinversion3.8:Returnedrowsarenowoftypedict. Ashortusageexample: >>>importcsv >>>withopen('names.csv',newline='')ascsvfile: ...reader=csv.DictReader(csvfile) ...forrowinreader: ...print(row['first_name'],row['last_name']) ... EricIdle JohnCleese >>>print(row) {'first_name':'John','last_name':'Cleese'} classcsv.DictWriter(f,fieldnames,restval='',extrasaction='raise',dialect='excel',*args,**kwds)¶ Createanobjectwhichoperateslikearegularwriterbutmapsdictionaries ontooutputrows.Thefieldnamesparameterisasequenceofkeysthatidentifytheorderinwhichvaluesinthe dictionarypassedtothewriterow()methodarewrittentofile f.Theoptionalrestvalparameterspecifiesthevaluetobe writtenifthedictionaryismissingakeyinfieldnames.Ifthe dictionarypassedtothewriterow()methodcontainsakeynotfoundin fieldnames,theoptionalextrasactionparameterindicateswhatactionto take. Ifitissetto'raise',thedefaultvalue,aValueError israised. Ifitissetto'ignore',extravaluesinthedictionaryareignored. Anyotheroptionalorkeywordargumentsarepassedtotheunderlying writerinstance. NotethatunliketheDictReaderclass,thefieldnamesparameter oftheDictWriterclassisnotoptional. Ashortusageexample: importcsv withopen('names.csv','w',newline='')ascsvfile: fieldnames=['first_name','last_name'] writer=csv.DictWriter(csvfile,fieldnames=fieldnames) writer.writeheader() writer.writerow({'first_name':'Baked','last_name':'Beans'}) writer.writerow({'first_name':'Lovely','last_name':'Spam'}) writer.writerow({'first_name':'Wonderful','last_name':'Spam'}) classcsv.Dialect¶ TheDialectclassisacontainerclasswhoseattributescontain informationforhowtohandledoublequotes,whitespace,delimiters,etc. DuetothelackofastrictCSVspecification,differentapplications producesubtlydifferentCSVdata.Dialectinstancesdefinehow readerandwriterinstancesbehave. AllavailableDialectnamesarereturnedbylist_dialects(), andtheycanberegisteredwithspecificreaderandwriter classesthroughtheirinitializer(__init__)functionslikethis: importcsv withopen('students.csv','w',newline='')ascsvfile: writer=csv.writer(csvfile,dialect='unix') ^^^^^^^^^^^^^^ classcsv.excel¶ TheexcelclassdefinestheusualpropertiesofanExcel-generatedCSV file.Itisregisteredwiththedialectname'excel'. classcsv.excel_tab¶ Theexcel_tabclassdefinestheusualpropertiesofanExcel-generated TAB-delimitedfile.Itisregisteredwiththedialectname'excel-tab'. classcsv.unix_dialect¶ Theunix_dialectclassdefinestheusualpropertiesofaCSVfile generatedonUNIXsystems,i.e.using'\n'aslineterminatorandquoting allfields.Itisregisteredwiththedialectname'unix'. Newinversion3.2. classcsv.Sniffer¶ TheSnifferclassisusedtodeducetheformatofaCSVfile. TheSnifferclassprovidestwomethods: sniff(sample,delimiters=None)¶ AnalyzethegivensampleandreturnaDialectsubclass reflectingtheparametersfound.Iftheoptionaldelimitersparameter isgiven,itisinterpretedasastringcontainingpossiblevalid delimitercharacters. has_header(sample)¶ Analyzethesampletext(presumedtobeinCSVformat)andreturn Trueifthefirstrowappearstobeaseriesofcolumnheaders. Inspectingeachcolumn,oneoftwokeycriteriawillbeconsideredto estimateifthesamplecontainsaheader: thesecondthroughn-throwscontainnumericvalues thesecondthroughn-throwscontainstringswhereatleastonevalue’s lengthdiffersfromthatoftheputativeheaderofthatcolumn. Twentyrowsafterthefirstrowaresampled;ifmorethanhalfofcolumns+ rowsmeetthecriteria,Trueisreturned. Note Thismethodisaroughheuristicandmayproducebothfalsepositivesand negatives. AnexampleforSnifferuse: withopen('example.csv',newline='')ascsvfile: dialect=csv.Sniffer().sniff(csvfile.read(1024)) csvfile.seek(0) reader=csv.reader(csvfile,dialect) #...processCSVfilecontentshere... Thecsvmoduledefinesthefollowingconstants: csv.QUOTE_ALL¶ Instructswriterobjectstoquoteallfields. csv.QUOTE_MINIMAL¶ Instructswriterobjectstoonlyquotethosefieldswhichcontain specialcharacterssuchasdelimiter,quotecharoranyofthecharactersin lineterminator. csv.QUOTE_NONNUMERIC¶ Instructswriterobjectstoquoteallnon-numericfields. Instructsthereadertoconvertallnon-quotedfieldstotypefloat. csv.QUOTE_NONE¶ Instructswriterobjectstoneverquotefields.Whenthecurrent delimiteroccursinoutputdataitisprecededbythecurrentescapechar character.Ifescapecharisnotset,thewriterwillraiseErrorif anycharactersthatrequireescapingareencountered. Instructsreadertoperformnospecialprocessingofquotecharacters. Thecsvmoduledefinesthefollowingexception: exceptioncsv.Error¶ Raisedbyanyofthefunctionswhenanerrorisdetected. DialectsandFormattingParameters¶ Tomakeiteasiertospecifytheformatofinputandoutputrecords,specific formattingparametersaregroupedtogetherintodialects.Adialectisa subclassoftheDialectclasshavingasetofspecificmethodsanda singlevalidate()method.Whencreatingreaderor writerobjects,theprogrammercanspecifyastringorasubclassof theDialectclassasthedialectparameter.Inadditionto,orinstead of,thedialectparameter,theprogrammercanalsospecifyindividual formattingparameters,whichhavethesamenamesastheattributesdefinedbelow fortheDialectclass. Dialectssupportthefollowingattributes: Dialect.delimiter¶ Aone-characterstringusedtoseparatefields.Itdefaultsto','. Dialect.doublequote¶ Controlshowinstancesofquotecharappearinginsideafieldshould themselvesbequoted.WhenTrue,thecharacterisdoubled.When False,theescapecharisusedasaprefixtothequotechar.It defaultstoTrue. Onoutput,ifdoublequoteisFalseandnoescapecharisset, Errorisraisedifaquotecharisfoundinafield. Dialect.escapechar¶ Aone-characterstringusedbythewritertoescapethedelimiterifquoting issettoQUOTE_NONEandthequotecharifdoublequoteis False.Onreading,theescapecharremovesanyspecialmeaningfrom thefollowingcharacter.ItdefaultstoNone,whichdisablesescaping. Dialect.lineterminator¶ Thestringusedtoterminatelinesproducedbythewriter.Itdefaults to'\r\n'. Note Thereaderishard-codedtorecogniseeither'\r'or'\n'as end-of-line,andignoreslineterminator.Thisbehaviormaychangeinthe future. Dialect.quotechar¶ Aone-characterstringusedtoquotefieldscontainingspecialcharacters,such asthedelimiterorquotechar,orwhichcontainnew-linecharacters.It defaultsto'"'. Dialect.quoting¶ Controlswhenquotesshouldbegeneratedbythewriterandrecognisedbythe reader.ItcantakeonanyoftheQUOTE_*constants(seesection ModuleContents)anddefaultstoQUOTE_MINIMAL. Dialect.skipinitialspace¶ WhenTrue,spacesimmediatelyfollowingthedelimiterareignored. ThedefaultisFalse. Dialect.strict¶ WhenTrue,raiseexceptionErroronbadCSVinput. ThedefaultisFalse. ReaderObjects¶ Readerobjects(DictReaderinstancesandobjectsreturnedbythe reader()function)havethefollowingpublicmethods: csvreader.__next__()¶ Returnthenextrowofthereader’siterableobjectasalist(iftheobject wasreturnedfromreader())oradict(ifitisaDictReader instance),parsedaccordingtothecurrentDialect.Usuallyyou shouldcallthisasnext(reader). Readerobjectshavethefollowingpublicattributes: csvreader.dialect¶ Aread-onlydescriptionofthedialectinusebytheparser. csvreader.line_num¶ Thenumberoflinesreadfromthesourceiterator.Thisisnotthesameasthe numberofrecordsreturned,asrecordscanspanmultiplelines. DictReaderobjectshavethefollowingpublicattribute: csvreader.fieldnames¶ Ifnotpassedasaparameterwhencreatingtheobject,thisattributeis initializeduponfirstaccessorwhenthefirstrecordisreadfromthe file. WriterObjects¶ Writerobjects(DictWriterinstancesandobjectsreturnedby thewriter()function)havethefollowingpublicmethods.Arowmustbe aniterableofstringsornumbersforWriterobjectsandadictionary mappingfieldnamestostringsornumbers(bypassingthemthroughstr() first)forDictWriterobjects.Notethatcomplexnumbersarewritten outsurroundedbyparens.Thismaycausesomeproblemsforotherprogramswhich readCSVfiles(assumingtheysupportcomplexnumbersatall). csvwriter.writerow(row)¶ Writetherowparametertothewriter’sfileobject,formattedaccording tothecurrentDialect.Returnthereturnvalueofthecalltothe writemethodoftheunderlyingfileobject. Changedinversion3.5:Addedsupportofarbitraryiterables. csvwriter.writerows(rows)¶ Writeallelementsinrows(aniterableofrowobjectsasdescribed above)tothewriter’sfileobject,formattedaccordingtothecurrent dialect. Writerobjectshavethefollowingpublicattribute: csvwriter.dialect¶ Aread-onlydescriptionofthedialectinusebythewriter. DictWriterobjectshavethefollowingpublicmethod: DictWriter.writeheader()¶ Writearowwiththefieldnames(asspecifiedintheconstructor)to thewriter’sfileobject,formattedaccordingtothecurrentdialect.Return thereturnvalueofthecsvwriter.writerow()callusedinternally. Newinversion3.2. Changedinversion3.8:writeheader()nowalsoreturnsthevaluereturnedby thecsvwriter.writerow()methoditusesinternally. Examples¶ ThesimplestexampleofreadingaCSVfile: importcsv withopen('some.csv',newline='')asf: reader=csv.reader(f) forrowinreader: print(row) Readingafilewithanalternateformat: importcsv withopen('passwd',newline='')asf: reader=csv.reader(f,delimiter=':',quoting=csv.QUOTE_NONE) forrowinreader: print(row) Thecorrespondingsimplestpossiblewritingexampleis: importcsv withopen('some.csv','w',newline='')asf: writer=csv.writer(f) writer.writerows(someiterable) Sinceopen()isusedtoopenaCSVfileforreading,thefile willbydefaultbedecodedintounicodeusingthesystemdefault encoding(seelocale.getpreferredencoding()).Todecodeafile usingadifferentencoding,usetheencodingargumentofopen: importcsv withopen('some.csv',newline='',encoding='utf-8')asf: reader=csv.reader(f) forrowinreader: print(row) Thesameappliestowritinginsomethingotherthanthesystemdefault encoding:specifytheencodingargumentwhenopeningtheoutputfile. Registeringanewdialect: importcsv csv.register_dialect('unixpwd',delimiter=':',quoting=csv.QUOTE_NONE) withopen('passwd',newline='')asf: reader=csv.reader(f,'unixpwd') Aslightlymoreadvanceduseofthereader—catchingandreportingerrors: importcsv,sys filename='some.csv' withopen(filename,newline='')asf: reader=csv.reader(f) try: forrowinreader: print(row) exceptcsv.Errorase: sys.exit('file{},line{}:{}'.format(filename,reader.line_num,e)) Andwhilethemoduledoesn’tdirectlysupportparsingstrings,itcaneasilybe done: importcsv forrowincsv.reader(['one,two,three']): print(row) Footnotes 1(1,2) Ifnewline=''isnotspecified,newlinesembeddedinsidequotedfields willnotbeinterpretedcorrectly,andonplatformsthatuse\r\nlinendings onwriteanextra\rwillbeadded.Itshouldalwaysbesafetospecify newline='',sincethecsvmoduledoesitsown (universal)newlinehandling. TableofContents csv—CSVFileReadingandWriting ModuleContents DialectsandFormattingParameters ReaderObjects WriterObjects Examples Previoustopic FileFormats Nexttopic configparser—Configurationfileparser ThisPage ReportaBug ShowSource Navigation index modules| next| previous| Python» 3.10.7Documentation» ThePythonStandardLibrary» FileFormats» csv—CSVFileReadingandWriting |