Skip to content

Commit a8c262e

Browse files
mrknmrkn
committed
Rewrite README
[skip ci]
1 parent fd14ca1 commit a8c262e

File tree

1 file changed

+41
-49
lines changed

1 file changed

+41
-49
lines changed

‎README.md

Lines changed: 41 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,10 @@
33
[![Build Status](https://travis-ci.org/mrkn/pycall.svg?branch=master)](https://travis-ci.org/mrkn/pycall)
44
[![Build status](https://ci.appveyor.com/api/projects/status/071is0f4iu0vy8lp/branch/master?svg=true)](https://ci.appveyor.com/project/mrkn/pycall/branch/master)
55

6-
This library provides the features to directly call and partially interoperate with Python from the Ruby language. You can import arbitrary Python modules into Ruby modules, call Python functions with automatic type conversion from Ruby to Python.
6+
This library provides the features to directly call and partially interoperate
7+
with Python from the Ruby language. You can import arbitrary Python modules
8+
into Ruby modules, call Python functions with automatic type conversion from
9+
Ruby to Python.
710

811
## Installation
912

@@ -23,77 +26,66 @@ Or install it yourself as:
2326

2427
## Usage
2528

26-
Here is a simple example to call Python's `math.sin` function and compare it to the `Math.sin` in Ruby:
29+
Here is a simple example to call Python's `math.sin` function and compare it to
30+
the `Math.sin` in Ruby:
2731

2832
require 'pycall/import'
2933
include PyCall::Import
3034
pyimport :math
31-
math.sin.(math.pi / 4) - Math.sin(Math::PI / 4) # => 0.0
32-
# ^ This period is necessary
35+
math.sin(math.pi / 4) - Math.sin(Math::PI / 4) # => 0.0
3336

34-
Type conversions from Ruby to Python are automatically performed for numeric, boolean, string, arrays, and hashes.
37+
Type conversions from Ruby to Python are automatically performed for numeric,
38+
boolean, string, arrays, and hashes.
3539

36-
### Python function call
40+
## PyCall object system
3741

38-
In this version of pycall, the all of functions and methods in Python is wrapped as callable objects in Ruby. It means we need to put a priod between the name of function and `(` like `math.sin.(...)` in the above example.
42+
PyCall wraps pointers of Python objects in `PyCall::PyPtr` objects.
43+
`PyCall::PyPtr` class has two subclasses, `PyCall::PyTypePtr` and
44+
`PyCall::PyRubyPtr`. `PyCall::PyTypePtr` is specialized for type (and classobj
45+
in 2.7) objects, and `PyCall::PyRubyPtr` is for the objects that wraps pointers
46+
of Ruby objects.
3947

40-
This unnatural notation is a temporary specification, so we should be able to write `math.sin(...)` in the future.
48+
These `PyCall::PyPtr` objects are used mainly in PyCall infrastructure.
49+
Instead, we usually treats the instances of `Object`, `Class`, `Module`, or
50+
other classes that are extended by `PyCall::PyObjectWrapper` module.
4151

42-
## Wrapping Python classes
43-
44-
**NOTE: Currently I'm trying to rewrite class wrapping system, so the content of this section will be changed.**
45-
46-
Using `PyCall::PyObjectWrapper` module, we can create incarnation classes for Python classes in Ruby language. For example, the following script defines a incarnation class for `numpy.ndarray` class.
47-
48-
```ruby
49-
require 'pycall'
50-
51-
class Ndarray
52-
import PyCall::PyObjectWrapper
53-
wrap_class PyCall.import_module('numpy').ndarray
54-
end
55-
```
56-
57-
Defineing incarnation classes using `wrap_class` registeres automatic type conversion, so it changes the class of wrapper object. For example:
58-
59-
require 'pycall/import'
60-
include PyCall::Import
61-
pyimport :numpy, as: :np
62-
x1 = np.array(PyCall.tuple(10))
63-
x1.class # => PyCall::PyObject
64-
65-
class Ndarray
66-
import PyCall::PyObjectWrapper
67-
wrap_class PyCall.import_module('numpy').ndarray
68-
# NOTE: From here, numpy.ndarray objects are converted to Ndarray objects
69-
end
70-
71-
x2 = np.array(PyCall.tuple(10))
72-
x2.class # => Ndarray
73-
74-
75-
**NOTE: I will write an efficient wrapper for numpy by RubyKaigi 2017.**
52+
`PyCall::PyObjectWrapper` is a mix-in module for objects that wraps Python
53+
objects. A wrapper object should have `PyCall::PyPtr` object in its instance
54+
variable `@__pyptr__`. `PyCall::PyObjectWrapper` assumes the existance of
55+
`@__pyptr__`, and provides general translation mechanisms between Ruby object
56+
system and Python object system. For example, `PyCall::PyObjectWrapper`
57+
translates Ruby's coerce system into Python's swapped operation protocol.
7658

7759
### Specifying the Python version
7860

79-
If you want to use a specific version of Python instead of the default, you can change the Python version by setting the `PYTHON` environment variable to the path of the `python` executable.
61+
If you want to use a specific version of Python instead of the default,
62+
you can change the Python version by setting the `PYTHON` environment variable
63+
to the path of the `python` executable.
8064

8165
## Development
8266

83-
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
67+
After checking out the repo, run `bin/setup` to install dependencies.
68+
Then, run `rake spec` to run the tests. You can also run `bin/console`
69+
for an interactive prompt that will allow you to experiment.
8470

85-
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
71+
To install this gem onto your local machine, run `bundle exec rake install`.
72+
To release a new version, update the version number in `version.rb`,
73+
and then run `bundle exec rake release`, which will create a git tag for the
74+
version, push git commits and tags, and push the `.gem` file to
75+
[rubygems.org](https://rubygems.org).
8676

8777
## Contributing
8878

89-
Bug reports and pull requests are welcome on GitHub at https://github.com/mrkn/pycall.
79+
Bug reports and pull requests are welcome on GitHub at
80+
https://github.com/mrkn/pycall.
9081

9182

9283
## Acknowledgement
9384

94-
[PyCall.jl](https://github.com/JuliaPy/PyCall.jl) is referred too many times to implement this library.
85+
[PyCall.jl](https://github.com/JuliaPy/PyCall.jl) is referred too many times
86+
to implement this library.
9587

9688
## License
9789

98-
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
99-
90+
The gem is available as open source under the terms of the
91+
[MIT License](http://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)