{"id":20643632,"url":"https://github.com/extrabacon/pyspreadsheet","last_synced_at":"2025-04-16T02:05:47.828Z","repository":{"id":9850939,"uuid":"11845096","full_name":"extrabacon/pyspreadsheet","owner":"extrabacon","description":"Python-based high performance spreadsheet API for Node","archived":false,"fork":false,"pushed_at":"2016-03-17T12:34:03.000Z","size":324,"stargazers_count":38,"open_issues_count":9,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-16T02:05:25.395Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/extrabacon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-02T14:27:52.000Z","updated_at":"2024-05-30T15:16:35.000Z","dependencies_parsed_at":"2022-08-30T23:40:16.895Z","dependency_job_id":null,"html_url":"https://github.com/extrabacon/pyspreadsheet","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/extrabacon%2Fpyspreadsheet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/extrabacon%2Fpyspreadsheet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/extrabacon%2Fpyspreadsheet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/extrabacon%2Fpyspreadsheet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/extrabacon","download_url":"https://codeload.github.com/extrabacon/pyspreadsheet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249183103,"owners_count":21226141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T16:13:27.918Z","updated_at":"2025-04-16T02:05:47.808Z","avatar_url":"https://github.com/extrabacon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PySpreadsheet\n\nA high-performance spreadsheet library for Node, powered by Python open source libraries. PySpreadsheet can be used\nto read and write Excel files in both XLS and XLSX formats.\n\nIMPORTANT: PySpreadsheet is a work in progress. This is not a stable release.\n\n## Features\n\n+ Faster and more memory efficient than most JS-only alternatives\n+ Uses child processes for isolation and parallelization (will not leak the Node process)\n+ Support for both XLS and XLSX formats\n+ Can stream large files with a familiar API\n+ Native integration with Javascript objects\n\n## Limitations\n\n+ Reading does not parse formats, only data\n+ Cannot edit existing files\n+ Basic XLS writing capabilities\n+ Incomplete API\n\n## Installation\n```bash\nnpm install pyspreadsheet\n```\n\nPython dependencies are installed automatically by downloading the latest version from their repositories. These dependencies are:\n\n+ [xlrd](http://github.com/python-excel/xlrd) and [xlwt](http://github.com/python-excel/xlwt), by Python Excel\n+ [XlsxWriter](http://github.com/jmcnamara/XlsxWriter), by John McNamara\n\n## Documentation\n\n### Reading a file with the `SpreadsheetReader` class\n\nUse the `SpreadsheetReader` class to read spreadsheet files. It can be used for reading an entire file into memory or as a stream-like object.\n\n#### Reading a file into memory\n\nReading a file into memory will output the entire contents of the file in an easy-to-use structure.\n\n```js\nvar SpreadsheetReader = require('pyspreadsheet').SpreadsheetReader;\n\nSpreadsheetReader.read('input.xlsx', function (err, workbook) {\n  // Iterate on sheets\n  workbook.sheets.forEach(function (sheet) {\n    console.log('sheet: %s', sheet.name);\n    // Iterate on rows\n    sheet.rows.forEach(function (row) {\n      // Iterate on cells\n      row.forEach(function (cell) {\n        console.log('%s: %s', cell.address, cell.value);\n      });\n    });\n  });\n});\n```\n\n#### Streaming a large file\n\nYou can use `SpreadsheetReader` just like a Node readable stream. This is the preferred method for reading larger files.\n\n```javascript\nvar SpreadsheetReader = require('pyspreadsheet').SpreadsheetReader;\nvar reader = new SpreadsheetReader('examples/sample.xlsx');\n\nreader.on('open', function (workbook) {\n  // file is open\n  console.log('opened ' + workbook.file);\n}).on('data', function (data) {\n  // data is being received\n  console.log('buffer contains %d rows from sheet \"%s\"', data.rows.length, data.sheet.name);\n}).on('close', function () {\n  // file is now closed\n  console.log('file closed');\n}).on('error', function (err) {\n  // got an error\n  throw err;\n});\n```\n\n### Writing a file with the `SpreadsheetWriter` class\n\nUse the `SpreadsheetWriter` class to write files. It can only write new files, it cannot edit existing files.\n\n```js\nvar SpreadsheetWriter = require('pyspreadsheet').SpreadsheetWriter;\nvar writer = new SpreadsheetWriter('examples/output.xlsx');\n\n// write a string at cell A1\nwriter.write(0, 0, 'hello world!');\n\nwriter.save(function (err) {\n  if (err) throw err;\n  console.log('file saved!');\n});\n```\n\n#### Adding sheets\n\nUse the `addSheet` method to add a new sheet. If data is written without adding a sheet first, a default \"Sheet1\" is automatically added.\n\n```js\nvar SpreadsheetWriter = require('pyspreadsheet').SpreadsheetWriter;\nvar writer = new SpreadsheetWriter('examples/output.xlsx');\nwriter.addSheet('my sheet').write(0, 0, 'hello');\n```\n\n#### Writing data\n\nUse the `write` method to write data to the designated cell. All Javascript built-in types are supported.\n\n```js\nwriter.write(0, 0, 'hello world!');\n```\n\n##### Formulas\n\nFormulas are parsed from strings. To write formulas, just prepend your string value with \"=\".\n\n```js\nwriter.write(2, 0, '=A1+A2');\n```\n\nNote that values calculated from formulas cannot be obtained until the file has been opened once with a spreadsheet client (like Microsoft Excel).\n\n##### Writing multiple cells\n\nUse arrays to write multiple cells at once horizontally.\n\n```js\nwriter.write(0, 0, ['a', 'b', 'c', 'd', 'e']);\n```\n\nUse two-dimensional arrays to write multiple rows at once.\n\n```js\nwriter.write(0, 0, [\n  ['a', 'b', 'c', 'd', 'e'],\n  ['1', '2', '3', '4', '5'],\n]);\n```\n\n### Formatting\n\nCells can be formatted by specifying format properties.\n\n```js\nwriter.write(0, 0, 'hello', {\n  font: {\n    name: 'Calibri',\n    size: 12\n  }\n});\n```\n\nFormats can also be reused by using the `addFormat` method.\n\n```js\nwriter.addFormat('title', {\n  font: { bold: true, color: '#ffffff' },\n  fill: '#000000'\n});\n\nwriter.write(0, 0, ['heading 1', 'heading 2', 'heading 3'], 'title');\n```\n\n## API Reference\n\n### SpreadsheetReader\n\nThe `SpreadsheetReader` is used to read spreadsheet files from various formats.\n\n#### #ctor(path, options)\n\nCreates a new `SpreadsheetReader` instance.\n\n* `path` - the path of the file to read, also accepting arrays for reading multiple files at once\n* `options` - the reading options (optional)\n  * `meta` - load only workbook metadata, without iterating on rows\n  * `sheet` || `sheets` - load sheet(s) selectively, either by name or by index\n  * `maxRows` - the maximum number of rows to load per sheet\n  * `bufferSize` - the maximum number of rows to accumulate in the buffer (default: 20)\n\n#### #read(path, options, callback)\n\nReads an entire file into memory.\n\n* `path` - the path of the file to read, also accepting arrays for reading multiple files at once\n* `options` - the reading options (optional)\n  * `meta` - load only workbook metadata, without iterating on rows\n  * `sheet` || `sheets` - load sheet(s) selectively, either by name or by index\n  * `maxRows` - the maximum number of rows to load per sheet\n* `callback(err, workbook)` - the callback function to invoke when the operation has completed\n  * `err` - the error, if any\n  * `workbook` - the parsed workbook instance, will be an array if `path` was also an array\n    * `file` - the file used to open the workbook\n    * `meta` - the metadata for this workbook\n      * `user` - the owner of the file\n      * `sheets` - an array of strings containing the name of sheets (available without iteration)\n    * `sheets` - the array of Sheet objects that were loaded\n      * `index` - the ordinal position of the sheet within the workbook\n      * `name` - the name of the sheet\n      * `bounds` - the data range for the sheet\n        * `rows` - the largest number of rows in the sheet\n        * `columns` - the largest number of columns in the sheet\n      * `visibility` - the sheet visibility, possible values are `visible`, `hidden` and `very hidden`\n      * `rows` - the array of rows that were loaded - rows are arrays of cells\n        * `row` - the ordinal row number\n        * `column` - the ordinal column number\n        * `address` - the cell address (\"A1\", \"B12\", etc.)\n        * `value` - the cell value, which can be of the following types:\n          * `Number` - for numeric values\n          * `Date` - for cells formatted as dates\n          * `Error` - for cells with errors (such as #NAME?)\n          * `Boolean` - for cells formatted as booleans\n          * `String` - for anything else\n      * `cell(address)` - a function returning the cell at a specific location (ex: B12), same as accessing the `rows` array\n\n#### Event: 'open'\n\nEmitted when a workbook file is open. The data included with this event includes:\n\n* `file` - the file used to open the workbook\n* `meta` - the metadata for this workbook\n  * `user` - the owner of the file\n  * `sheets` - an array of strings containing the name of sheets (available without iteration)\n\nThis event can be emitted more than once if multiple files are being read.\n\n#### Event: 'data'\n\nEmitted as rows are being read from the file. The data for this event consists of:\n\n* `sheet` - the currently open sheet\n  * `index` - the ordinal position of the sheet within the workbook\n  * `name` - the sheet name\n  * `bounds` - the data range for the sheet\n    * `rows` - the largest number of rows in the sheet\n    * `columns` - the largest number of columns in the sheet\n  * `visibility` - the sheet visibility, possible values are `visible`, `hidden` and `very hidden`\n* `rows` - the array of rows that were loaded (number of rows returned depend on the buffer size)\n  * `row` - the ordinal row number\n  * `column` - the ordinal column number\n  * `address` - the cell address (\"A1\", \"B12\", etc.)\n  * `value` - the cell value, which can be of the following types:\n    * `Number` - for numeric values\n    * `Date` - for cells formatted as dates\n    * `Error` - for cells with errors, such as #NAME?\n    * `Boolean` - for cells formatted as booleans\n    * `String` - for anything else\n\n#### Event: 'close'\n\nEmitted when a workbook file is closed. This event can be emitted more than once if multiple files are being read.\n\n#### Event: 'error'\n\nEmitted when an error is encountered.\n\n### SpreadsheetWriter\n\nThe `SpreadsheetWriter` is used to write spreadsheet files into various formats. All writer methods return the same instance, so feel free to chain your calls.\n\n#### #ctor(path, options)\n\nCreates a new `SpreadsheetWriter` instance.\n\n* `path` - the path of the file to write\n* `options` - the writer options (optional)\n  * `format` - the file format\n  * `defaultDateFormat` - the default date format (only for XLSX files)\n  * `properties` - the workbook properties\n    * `title`\n    * `subject`\n    * `author`\n    * `manager`\n    * `company`\n    * `category`\n    * `keywords`\n    * `comments`\n    * `status`\n\n#### .addSheet(name, options)\n\nAdds a new sheet to the workbook.\n\n* `name` - the sheet name (must be unique within the workbook)\n* `options` - the sheet options\n  * `hidden`\n  * `activated`\n  * `selected`\n  * `rightToLeft`\n  * `hideZeroValues`\n  * `selection`\n\n#### .activateSheet(sheet)\n\nActivates a previously added sheet.\n\n* `sheet` - the sheet name or index\n\n#### .addFormat(name, properties)\n\nRegisters a reusable format.\n\n* `name` - the format name\n* `properties` - the formatting properties\n  * `font`\n    * `name`\n    * `size`\n    * `color`\n    * `bold`\n    * `italic`\n    * `underline`\n    * `strikeout`\n    * `superscript`\n    * `subscript`\n  * `numberFormat`\n  * `locked`\n  * `hidden`\n  * `alignment`\n  * `rotation`\n  * `indent`\n  * `shrinkToFit`\n  * `justifyLastText`\n  * `fill`\n    * `pattern`\n    * `backgroundColor`\n    * `foregroundColor`\n  * `borders`\n    * `top` | `left` | `right` | `bottom`\n      * `style`\n      * `color`\n\n#### .write(row, column, data, format)\n\nWrites data to the specified cell with an optional format.\n\n* `row` - the row index\n* `column` - the column index\n* `data` - the value to write, supported types are: String, Number, Date, Boolean and Array\n* `format` - the format name or properties to use (optional)\n\n#### .write(cell, data, format)\n\nSame as previous, except cell is a string such as \"A1\", \"B2\" or \"1,1\"\n\n#### .append(data, format)\n\nAppends data at the first column of the next row. The next row is determined by the last call to `write`.\n\n* `data` - the value to write (use arrays to write multiple cells at once)\n* `format` - the format name or properties to use (optional)\n\n#### .save(callback)\n\nSave and close the resulting workbook file.\n\n* `callback(err)` - the callback function to invoke when the file is saved\n  * `err` - the error, if any\n\n#### Event: open\n\nEmitted when the file is open.\n\n#### Event: close\n\nEmitted when the file is closed.\n\n#### Event: error\n\nEmitted when an error occurs.\n\n## Compatibility\n\n+ Tested with Node 0.10.x\n+ Tested on Mac OS X 10.8\n+ Tested on Ubuntu Linux 12.04\n+ Tested on Heroku\n\n## Dependencies\n\n+ Python version 2.7+\n+ [xlrd](http://www.python-excel.org/) version 0.7.4+\n+ [xlwt](http://www.python-excel.org/) version 0.7.5+\n+ [XlsxWriter](http://xlsxwriter.readthedocs.org/en/latest/index.html) version 0.3.6+\n+ bash (installation script)\n+ git (installation script)\n\n## License\n\nThe MIT License (MIT)\n\nCopyright (c) 2013 Nicolas Mercier\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fextrabacon%2Fpyspreadsheet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fextrabacon%2Fpyspreadsheet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fextrabacon%2Fpyspreadsheet/lists"}