python-pickle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea86f43e4b83bacac94635b88e2c9deeb6eb4aaa553f1770e4943554389422fc
+  data.tar.gz: 973327ecbd8f2c1df7d0ac10f37d76628745e00da9317ab655a9f12644fef441
+SHA512:
+  metadata.gz: 8b95a73ff2ebfba7c9ca97648df7c7b3b6be14df61e0e6f4943e3e263a5f300696e79d8cf57aacc7bd9d572bcf3c00a5ec88162e1dd8cc627617afe01414499d
+  data.tar.gz: 73a9a106cfa346d3d74835cf9369732f041fdb2faafdb8a030f1e9ec6b58831e8b7c8aee3a05bec687d11d2d4ea9d48a00d4fcf164f0c686eb84c1248b15f056

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.*
+LICENSE.txt

data/.github/workflows/ruby.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 3.0
+          - 3.1
+          - 3.2
+          - jruby
+          # - truffleruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,5 @@
+/Gemfile.lock
+/coverage
+/doc/
+/pkg/
+/vendor/bundle/

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "Python::Pickle Documentation" --protected --quiet

data/ChangeLog.md

@@ -0,0 +1,14 @@
+### 0.1.0 / 2023-02-18
+
+* Initial release:
+  * Supports deserializing Python Pickle data into Ruby objects.
+  * Supports serializing Ruby objects into Python Pickle data.
+  * Optionally supports only parsing Python Pickle data streams for debugging
+    purposes.
+  * Supports Pickle protocol 0, protocol 1, protocol 2, protocol 3, protocol 4,
+    and protocol 5.
+    * Can parse both Python 2 and Python 3 Pickled data.
+  * Supports deserializing Python `tuple` and `bytearray` objects.
+  * Supports mapping Python functions to Ruby methods.
+  * Supports mapping Python classes to Ruby classes.
+

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+  gem 'rspec',          '~> 3.0'
+  gem 'simplecov',      '~> 0.20'
+  gem 'kramdown'
+  gem 'redcarpet',       platform: :mri
+  gem 'yard',           '~> 0.9'
+  gem 'yard-spellcheck', require: false
+  gem 'dead_end',        require: false
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2023 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# python-pickle.rb
+
+[![CI](https://github.com/postmodern/python-pickle.rb/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/python-pickle.rb/actions/workflows/ruby.yml)
+[![Gem Version](https://badge.fury.io/rb/python-pickle.svg)](https://badge.fury.io/rb/python-pickle)
+
+* [Source](https://github.com/postmodern/python-pickle.rb)
+* [Issues](https://github.com/postmodern/python-pickle.rb/issues)
+* [Documentation](https://rubydoc.info/gems/python-pickle)
+
+## Description
+
+python-pickle is a modern Ruby implementation of the Python Pickle serialization
+format.
+
+## Features
+
+* Supports deserializing Python Pickle data into Ruby objects.
+* Optionally supports only parsing Python Pickle data streams for debugging
+  purposes.
+* Supports Pickle protocol 0, protocol 1, protocol 2, protocol 3, protocol 4,
+  and protocol 5.
+  * Can parse both Python 2 and Python 3 Pickled data.
+* Supports deserializing Python `tuple` and `bytearray` objects.
+* Supports mapping Python functions to Ruby methods.
+* Supports mapping Python classes to Ruby classes.
+
+## TODO
+
+* Add support for writing Python Pickle data.
+* Add support for serializing Ruby objects to Python Pickle data.
+
+## Requirements
+
+* [Ruby] >= 3.0.0
+
+[Ruby]: https://www.ruby-lang.org/
+
+## Install
+
+```shell
+$ gem install python-pickle
+```
+
+### gemspec
+
+```ruby
+gem.add_dependency 'python-pickle', '~> 1.0'
+```
+
+### Gemfile
+
+```ruby
+gem 'python-pickle', '~> 1.0'
+```
+
+## Examples
+
+Load a Python Pickle string:
+
+```ruby
+Python::Pickle.load("\x80\x04\x95\x10\x00\x00\x00\x00\x00\x00\x00}\x94\x8C\x03foo\x94\x8C\x03bar\x94s.")
+# => {"foo"=>"bar"}
+```
+
+Load a Python Pickle stream:
+
+```ruby
+Python::Pickle.load(io)
+# => ...
+```
+
+Loading a Python Pickle file:
+
+```ruby
+Python::Pickle.load_file('dict.pkl')
+# => {"foo"=>"bar"}
+```
+
+Loading Python `bytearray` objects:
+
+```ruby
+pickle = "\x80\x05\x95\x0E\x00\x00\x00\x00\x00\x00\x00\x96\x03\x00\x00\x00\x00\x00\x00\x00ABC\x94."
+
+Python::Pickle.load(pickle)
+# => #<Python::Pickle::ByteArray: "ABC">
+```
+
+Loading Python objects:
+
+```ruby
+ickle = "\x80\x04\x95,\x00\x00\x00\x00\x00\x00\x00\x8C\b__main__\x94\x8C\aMyClass\x94\x93\x94)\x81\x94}\x94(\x8C\x01x\x94KA\x8C\x01y\x94KBub."
+
+Python::Pickle.load(pickle)
+# => 
+# #<Python::Pickle::PyObject:0x00007f48c9ba7598                   
+#  @attributes={"y"=>66, "x"=>65},                                
+#  @init_args=[],                                                 
+#  @init_kwargs={},                                               
+#  @py_class=#<Python::Pickle::PyClass: __main__.MyClass>>        
+```
+
+Mapping Python classes to Ruby classes:
+
+```ruby
+class MyClass
+
+  attr_reader :x
+  attr_reader :y
+
+  def __setstate__(attributes)
+    @x = attributes['x']
+    @y = attributes['y']
+  end
+
+end
+
+pickle = "\x80\x04\x95,\x00\x00\x00\x00\x00\x00\x00\x8C\b__main__\x94\x8C\aMyClass\x94\x93\x94)\x81\x94}\x94(\x8C\x01x\x94KA\x8C\x01y\x94KBub."
+
+Python::Pickle.load(pickle, constants: {
+  '__main__' => {
+    'MyClass' => MyClass
+  }
+})
+# => #<MyClass:0x00007f48c5c28980 @x=65, @y=66>
+```
+
+Parsing and inspecting a pickle file:
+
+```ruby
+require 'python/pickle'
+
+Python::Pickle.parse(File.open('dict.pkl'))
+# => 
+# [#<Python::Pickle::Instructions::Mark: MARK>,
+#  #<Python::Pickle::Instructions::Dict: DICT>,
+#  #<Python::Pickle::Instructions::Put: PUT 0>,
+#  #<Python::Pickle::Instructions::String: STRING "foo">,
+#  #<Python::Pickle::Instructions::Put: PUT 1>,
+#  #<Python::Pickle::Instructions::String: STRING "bar">,
+#  #<Python::Pickle::Instructions::Put: PUT 2>,
+#  #<Python::Pickle::Instructions::SetItem: SETITEM>,
+#  #<Python::Pickle::Instructions::Stop: STOP>]
+```
+
+## Copyright
+
+Copyright (c) 2023 Hal Brodigan
+
+See {file:LICENSE.txt} for details.

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new  
+task :doc => :yard

data/gemspec.yml

@@ -0,0 +1,25 @@
+name: python-pickle
+summary: A modern Ruby implementation of the Python Pickle serialization format.
+description: |
+  python-pickle is a modern Ruby implementation of the Python Pickle
+  serialization format. It supports protocol 0, protocol 1, protocol 2,
+  protocol 3, protocol 4, and protocol 5, allowing it to parse both Python 2
+  and Python 3 pickle data.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/python-pickle.rb#readme
+has_yard: true
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/python-pickle
+  source_code_uri:   https://github.com/postmodern/python-pickle.rb
+  bug_tracker_uri:   https://github.com/postmodern/python-pickle.rb/issues
+  changelog_uri:     https://github.com/postmodern/python-pickle.rb/blob/master/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+required_ruby_version: ">= 3.0.0"
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/python/pickle/byte_array.rb

@@ -0,0 +1,40 @@
+module Python
+  module Pickle
+    #
+    # Represents a Python `bytearray` object.
+    #
+    class ByteArray < String
+
+      # Mapping of python `codecs` encoding names and their Ruby equivalents.
+      #
+      # @api private
+      ENCODINGS = {
+        nil       => Encoding::ASCII_8BIT,
+        'latin-1' => Encoding::ISO_8859_1
+      }
+
+      #
+      # Initializes the byte array.
+      #
+      # @param [String] string
+      #   The contents of the byte array.
+      #
+      # @param [String, nil] encoding
+      #   The optional encoding name.
+      #
+      def initialize(string='', encoding=nil)
+        super(string, encoding: ENCODINGS.fetch(encoding))
+      end
+
+      #
+      # Inspects the byte array object.
+      #
+      # @return [String]
+      #
+      def inspect
+        "#<#{self.class}: #{super}>"
+      end
+
+    end
+  end
+end