"csv" --- Baca dan Tulis file CSV
*********************************

**Kode sumber:** Lib/csv.py

======================================================================

Format CSV (Comma Separated Values) adalah format impor dan ekspor
data yang paling umum digunakan untuk data spreadsheet dan database.
Format CSV telah digunakan selama bertahun-tahun sebelum adanya upaya
untuk mendeskripsikan format yang distandardisasi pada **RFC 4180**.
Kurangnya standar yang terdefinisi dengan baik berarti banyak
perbedaan tipis pada data yang dihasilkan dan digunakan dengan
penggunaan yang berbeda. Perbedaan tersebut membuat tidak mudah untuk
memproses file CSV dari beberapa sumber. Namun, meskipun karakter
pembatas dan kutipan berbeda-beda, keseluruhan formatnya cukup mirip
sehingga memungkinkan untuk menulis sebuah modul yang secara efisien
dapat memanipulasi data tersebut.

Modul "csv" mengimplementasikan kelas-kelas untuk membaca dan menulis
data tabular dengan format CSV.  Hal ini memungkinkan pemrogram untuk
mengatakan, "tulis data ini dalam format yang disukai oleh Excel,"
atau "baca data dari file ini yang dihasilkan oleh Excel," tanpa
mengetahui detail persis dari format CSV yang digunakan oleh Excel.
Pemrogram juga bisa mendeskripsikan format CSV yang dapat dipahami
oleh aplikasi lain atau menentukan format CSV nya sendiri dengan
tujuan tertentu.

Modul milik "csv", "reader" dan "writer" objek membaca dan menulis
urutan-urutan.  Pemrogram juga bisa membaca dan menulis data dalam
bentuk dictionary dengan menggunakan kelas "DictReader" dan
"DictWriter".

Lihat juga:

  **PEP 305** - API File CSV
     Python Enhancement Proposal (PEP) yang mengusulkan penambahan ini
     ke Python.


Modul-Modul
===========

Modul "csv" memiliki fungsi-fungsi sebagai berikut:

csv.reader(csvfile, dialect='excel', **fmtparams)

   Mengembalikan sebuah objek reader yang mengiterasikan baris baris
   pada *csvfile* yang diberikan. *csvfile* dapat berupa segala objek
   yang mendukung protokol *iterator* dan mengembalikan string setiap
   kali metode "__next__()" dipanggil --- *objek file* dan objek list
   keduanya cocok digunakan.   Jika *csvfile* merupakan objek file,
   harus dibuka dengan "newline=''". [1]  Sebuah parameter *dialek*
   opsional dapat diberikan untuk mendefinisikan sebuah set parameter
   khusus untuk dialek CSV tertentu.  Mungkin merupakan instansi
   sebuah subkelas dari kelas "Dialect" atau salah satu string yang
   dikembalikan oleh fungsi "list_dialects()".  Argumen kata kunci
   opsional *fmtparams* lainnya dapat diberikan untuk menimpa
   parameter-parameter pemformatan individu dalam dialek saat ini.
   Untuk detail lebih jelas mengenai dialek dan parameter format,
   lihat Dialek dan Parameter Pemformatan.

   Setiap baris yang dibaca dari file csv dikembalikan sebagai list
   yang berisi strings.  Tidak ada konversi tipe data secara otomatis
   dilakukan kecuali kalau opsi format "QUOTE_NONNUMERIC" ditentukan
   (dalam hal ini, bidang tanpa tanda kutip diubah menjadi bertipe
   floats).

   Contoh penggunaan singkat:

      >>> import csv
      >>> with open('eggs.csv', newline='') as csvfile:
      ...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
      ...     for row in spamreader:
      ...         print(', '.join(row))
      Spam, Spam, Spam, Spam, Spam, Baked Beans
      Spam, Lovely Spam, Wonderful Spam

csv.writer(csvfile, dialect='excel', **fmtparams)

   Return a writer object responsible for converting the user's data
   into delimited strings on the given file-like object.  *csvfile*
   can be any object with a "write()" method.  If *csvfile* is a file
   object, it should be opened with "newline=''" [1].  An optional
   *dialect* parameter can be given which is used to define a set of
   parameters specific to a particular CSV dialect.  It may be an
   instance of a subclass of the "Dialect" class or one of the strings
   returned by the "list_dialects()" function.  The other optional
   *fmtparams* keyword arguments can be given to override individual
   formatting parameters in the current dialect.  For full details
   about dialects and formatting parameters, see the Dialek dan
   Parameter Pemformatan section. To make it as easy as possible to
   interface with modules which implement the DB API, the value "None"
   is written as the empty string.  While this isn't a reversible
   transformation, it makes it easier to dump SQL NULL data values to
   CSV files without preprocessing the data returned from a
   "cursor.fetch*" call. All other non-string data are stringified
   with "str()" before being written.

   Contoh penggunaan singkat:

      import csv
      with open('eggs.csv', 'w', newline='') as csvfile:
          spamwriter = csv.writer(csvfile, delimiter=' ',
                                  quotechar='|', quoting=csv.QUOTE_MINIMAL)
          spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
          spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])

csv.register_dialect(name[, dialect[, **fmtparams]])

   Associate *dialect* with *name*.  *name* must be a string. The
   dialect can be specified either by passing a sub-class of
   "Dialect", or by *fmtparams* keyword arguments, or both, with
   keyword arguments overriding parameters of the dialect. For full
   details about dialects and formatting parameters, see section
   Dialek dan Parameter Pemformatan.

csv.unregister_dialect(name)

   Delete the dialect associated with *name* from the dialect
   registry.  An "Error" is raised if *name* is not a registered
   dialect name.

csv.get_dialect(name)

   Return the dialect associated with *name*.  An "Error" is raised if
   *name* is not a registered dialect name.  This function returns an
   immutable "Dialect".

csv.list_dialects()

   Mengembalikan nama dari semua dialek yang terdaftar.

csv.field_size_limit([new_limit])

   Mengembalikan nilai maksimum ukuran field yang diperbolekan saat
   ini oleh parser. Jika  *new_limit* diberikan, hal tersebut menjadi
   limit baru.

Modul "csv" berisi kelas-kelas dibawah ini:

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

   Create an object that operates like a regular reader but maps the
   information in each row to a "dict" whose keys are given by the
   optional *fieldnames* parameter.

   The *fieldnames* parameter is a *sequence*.  If *fieldnames* is
   omitted, the values in the first row of file *f* will be used as
   the fieldnames.  Regardless of how the fieldnames are determined,
   the dictionary preserves their original ordering.

   If a row has more fields than fieldnames, the remaining data is put
   in a list and stored with the fieldname specified by *restkey*
   (which defaults to "None").  If a non-blank row has fewer fields
   than fieldnames, the missing values are filled-in with the value of
   *restval* (which defaults to "None").

   All other optional or keyword arguments are passed to the
   underlying "reader" instance.

   Berubah pada versi 3.6: Baris-baris yang dikembalikan sekarang
   memiliki tipe "OrderedDict".

   Berubah pada versi 3.8: Baris-baris yang dikembalikan sekarang
   memiliki tipe "dict".

   Contoh penggunaan singkat:

      >>> import csv
      >>> with open('names.csv', newline='') as csvfile:
      ...     reader = csv.DictReader(csvfile)
      ...     for row in reader:
      ...         print(row['first_name'], row['last_name'])
      ...
      Eric Idle
      John Cleese

      >>> print(row)
      {'first_name': 'John', 'last_name': 'Cleese'}

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

   Create an object which operates like a regular writer but maps
   dictionaries onto output rows.  The *fieldnames* parameter is a
   "sequence" of keys that identify the order in which values in the
   dictionary passed to the "writerow()" method are written to file
   *f*.  The optional *restval* parameter specifies the value to be
   written if the dictionary is missing a key in *fieldnames*.  If the
   dictionary passed to the "writerow()" method contains a key not
   found in *fieldnames*, the optional *extrasaction* parameter
   indicates what action to take. If it is set to "'raise'", the
   default value, a "ValueError" is raised. If it is set to
   "'ignore'", extra values in the dictionary are ignored. Any other
   optional or keyword arguments are passed to the underlying "writer"
   instance.

   Note that unlike the "DictReader" class, the *fieldnames* parameter
   of the "DictWriter" class is not optional.

   Contoh penggunaan singkat:

      import csv

      with open('names.csv', 'w', newline='') as csvfile:
          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'})

class csv.Dialect

   The "Dialect" class is a container class whose attributes contain
   information for how to handle doublequotes, whitespace, delimiters,
   etc. Due to the lack of a strict CSV specification, different
   applications produce subtly different CSV data.  "Dialect"
   instances define how "reader" and "writer" instances behave.

   All available "Dialect" names are returned by "list_dialects()",
   and they can be registered with specific "reader" and "writer"
   classes through their initializer ("__init__") functions like this:

      import csv

      with open('students.csv', 'w', newline='') as csvfile:
          writer = csv.writer(csvfile, dialect='unix')
                                       ^^^^^^^^^^^^^^

class csv.excel

   The "excel" class defines the usual properties of an Excel-
   generated CSV file.  It is registered with the dialect name
   "'excel'".

class csv.excel_tab

   The "excel_tab" class defines the usual properties of an Excel-
   generated TAB-delimited file.  It is registered with the dialect
   name "'excel-tab'".

class csv.unix_dialect

   The "unix_dialect" class defines the usual properties of a CSV file
   generated on UNIX systems, i.e. using "'\n'" as line terminator and
   quoting all fields.  It is registered with the dialect name
   "'unix'".

   Baru pada versi 3.2.

class csv.Sniffer

   Kelas "Sniffer" digunakan untuk menyimpulkan format sebuah file
   CSV.

   Kelas "Sniffer" menyediakan dua metode:

   sniff(sample, delimiters=None)

      Analyze the given *sample* and return a "Dialect" subclass
      reflecting the parameters found.  If the optional *delimiters*
      parameter is given, it is interpreted as a string containing
      possible valid delimiter characters.

   has_header(sample)

      Analyze the sample text (presumed to be in CSV format) and
      return "True" if the first row appears to be a series of column
      headers.

Sebuah contoh untuk penggunaan "Sniffer":

   with open('example.csv', newline='') as csvfile:
       dialect = csv.Sniffer().sniff(csvfile.read(1024))
       csvfile.seek(0)
       reader = csv.reader(csvfile, dialect)
       # ... process CSV file contents here ...

The "csv" module defines the following constants:

csv.QUOTE_ALL

   Menginstruksikan objek "writer" untuk mengutip semua fields.

csv.QUOTE_MINIMAL

   Menginstruksikan objek "writer" untuk hanya mengutip fields yang
   berisi karakter spesial seperti *delimiter*, *quotechar* atau salah
   satu karakter dalam *lineterminator*.

csv.QUOTE_NONNUMERIC

   Menginstuksikan objek "writer" untuk mengutip semua fields yang
   tidak memiliki angka.

   Mengisntruksikan reader untuk mengonversi semua fields yang tidak
   dikutip menjadi tipe *float*.

csv.QUOTE_NONE

   Instructs "writer" objects to never quote fields.  When the current
   *delimiter* occurs in output data it is preceded by the current
   *escapechar* character.  If *escapechar* is not set, the writer
   will raise "Error" if any characters that require escaping are
   encountered.

   Menginstruksikan "reader" untuk tidak melakukan pemrosesan khusus
   terhadap karakter kutipan

Modul "csv" berisi exception dibawah ini:

exception csv.Error

   Raised by any of the functions when an error is detected.


Dialek dan Parameter Pemformatan
================================

To make it easier to specify the format of input and output records,
specific formatting parameters are grouped together into dialects.  A
dialect is a subclass of the "Dialect" class having a set of specific
methods and a single "validate()" method.  When creating "reader" or
"writer" objects, the programmer can specify a string or a subclass of
the "Dialect" class as the dialect parameter.  In addition to, or
instead of, the *dialect* parameter, the programmer can also specify
individual formatting parameters, which have the same names as the
attributes defined below for the "Dialect" class.

Dialek mendukung atribut dibawah ini:

Dialect.delimiter

   Sebuah karakter yang digunakan sebagai pemisah fields. Dengan nilai
   bawaan "','".

Dialect.doublequote

   Controls how instances of *quotechar* appearing inside a field
   should themselves be quoted.  When "True", the character is
   doubled. When "False", the *escapechar* is used as a prefix to the
   *quotechar*.  It defaults to "True".

   On output, if *doublequote* is "False" and no *escapechar* is set,
   "Error" is raised if a *quotechar* is found in a field.

Dialect.escapechar

   A one-character string used by the writer to escape the *delimiter*
   if *quoting* is set to "QUOTE_NONE" and the *quotechar* if
   *doublequote* is "False". On reading, the *escapechar* removes any
   special meaning from the following character. It defaults to
   "None", which disables escaping.

Dialect.lineterminator

   The string used to terminate lines produced by the "writer". It
   defaults to "'\r\n'".

   Catatan:

     The "reader" is hard-coded to recognise either "'\r'" or "'\n'"
     as end-of-line, and ignores *lineterminator*. This behavior may
     change in the future.

Dialect.quotechar

   A one-character string used to quote fields containing special
   characters, such as the *delimiter* or *quotechar*, or which
   contain new-line characters.  It defaults to "'"'".

Dialect.quoting

   Controls when quotes should be generated by the writer and
   recognised by the reader.  It can take on any of the "QUOTE_*"
   constants (see section Modul-Modul) and defaults to
   "QUOTE_MINIMAL".

Dialect.skipinitialspace

   When "True", whitespace immediately following the *delimiter* is
   ignored. The default is "False".

Dialect.strict

   When "True", raise exception "Error" on bad CSV input. The default
   is "False".


Reader Objects
==============

Reader objects ("DictReader" instances and objects returned by the
"reader()" function) have the following public methods:

csvreader.__next__()

   Return the next row of the reader's iterable object as a list (if
   the object was returned from "reader()") or a dict (if it is a
   "DictReader" instance), parsed according to the current "Dialect".
   Usually you should call this as "next(reader)".

Reader objects have the following public attributes:

csvreader.dialect

   A read-only description of the dialect in use by the parser.

csvreader.line_num

   The number of lines read from the source iterator. This is not the
   same as the number of records returned, as records can span
   multiple lines.

Objek DictReader memiliki atribut publik sebagai berikut:

csvreader.fieldnames

   If not passed as a parameter when creating the object, this
   attribute is initialized upon first access or when the first record
   is read from the file.


Writer Objects
==============

"Writer" objects ("DictWriter" instances and objects returned by the
"writer()" function) have the following public methods.  A *row* must
be an iterable of strings or numbers for "Writer" objects and a
dictionary mapping fieldnames to strings or numbers (by passing them
through "str()" first) for "DictWriter" objects.  Note that complex
numbers are written out surrounded by parens. This may cause some
problems for other programs which read CSV files (assuming they
support complex numbers at all).

csvwriter.writerow(row)

   Write the *row* parameter to the writer's file object, formatted
   according to the current "Dialect". Return the return value of the
   call to the *write* method of the underlying file object.

   Berubah pada versi 3.5: Added support of arbitrary iterables.

csvwriter.writerows(rows)

   Write all elements in *rows* (an iterable of *row* objects as
   described above) to the writer's file object, formatted according
   to the current dialect.

Writer objects have the following public attribute:

csvwriter.dialect

   A read-only description of the dialect in use by the writer.

Objek DictWriter memiliki metode publik sebagai berikut:

DictWriter.writeheader()

   Write a row with the field names (as specified in the constructor)
   to the writer's file object, formatted according to the current
   dialect. Return the return value of the "csvwriter.writerow()" call
   used internally.

   Baru pada versi 3.2.

   Berubah pada versi 3.8: "writeheader()" now also returns the value
   returned by the "csvwriter.writerow()" method it uses internally.


Contoh-contoh
=============

Contoh paling sederhana dari membaca sebuah file CSV:

   import csv
   with open('some.csv', newline='') as f:
       reader = csv.reader(f)
       for row in reader:
           print(row)

Membaca file dengan format lain:

   import csv
   with open('passwd', newline='') as f:
       reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
       for row in reader:
           print(row)

Contoh paling sederhana dari menulis ke sebuah file CSV:

   import csv
   with open('some.csv', 'w', newline='') as f:
       writer = csv.writer(f)
       writer.writerows(someiterable)

Karena "open()" digunakan untuk membaca file CSV, file secara default
akan diterjemahkan menjadi unicode menggunakan default encoding dari
sistem (lihat "locale.getpreferredencoding()"). Untuk menerjemahkan
sebuah file dengan encoding yang berbeda, gunakan argumen "encoding"
pada "open()":

   import csv
   with open('some.csv', newline='', encoding='utf-8') as f:
       reader = csv.reader(f)
       for row in reader:
           print(row)

Hal yang sama berlaku ketika menulis sesuatu yang berbeda dengan
default encoding dari sistem: tentukan argumen encoding ketika membuka
file output.

Mendaftarkan dialek baru:

   import csv
   csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
   with open('passwd', newline='') as f:
       reader = csv.reader(f, 'unixpwd')

A slightly more advanced use of the reader --- catching and reporting
errors:

   import csv, sys
   filename = 'some.csv'
   with open(filename, newline='') as f:
       reader = csv.reader(f)
       try:
           for row in reader:
               print(row)
       except csv.Error as e:
           sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))

And while the module doesn't directly support parsing strings, it can
easily be done:

   import csv
   for row in csv.reader(['one,two,three']):
       print(row)

-[ Catatan kaki ]-

[1] If "newline=''" is not specified, newlines embedded inside quoted
    fields will not be interpreted correctly, and on platforms that
    use "\r\n" linendings on write an extra "\r" will be added.  It
    should always be safe to specify "newline=''", since the csv
    module does its own (*universal*) newline handling.
