docs: Added documentation for python bindings (#146)

* docs: Added documentation for python bindings

Signed-off-by: Yash Pandey (YP) <[email protected]>

* fix: error on ubuntu

Signed-off-by: Yash Pandey (YP) <[email protected]>

Author: EmperorYP7

CMakeLists.txt

@@ -55,11 +55,16 @@ option(CASBIN_BUILD_TEST "State whether to build test" ON)
 option(CASBIN_BUILD_BENCHMARK "State whether to build benchmarks" ON)
 option(CASBIN_BUILD_BINDINGS "State whether to build language bindings" ON)
 option(CASBIN_BUILD_PYTHON_BINDINGS "State whether to build python bindings" ON)
+option(CASBIN_INSTALL "State whether to install casbin targets on the current system" ON)
 
+# Intrinsic directory paths
+set(CASBIN_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/casbin)
+set(CASBIN_ROOT_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+set(CASBIN_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include)
 
 # Do not output install messages.
 if(NOT DEFINED CMAKE_INSTALL_MESSAGE)
-    set(CMAKE_INSTALL_MESSAGE "NEVER")
+    set(CMAKE_INSTALL_MESSAGE "LAZY")
 endif()
 
 if(CASBIN_BUILD_BINDINGS)
@@ -88,3 +93,24 @@ set(CMAKE_CXX_STANDARD 17)
 include(FindExtPackages)
 
 add_subdirectory(casbin)
+
+if(CASBIN_INSTALL)
+    message(CHECK_START "[casbin]: Installing casbin ...")
+    export(
+        TARGETS casbin
+        NAMESPACE casbin::
+        FILE casbinTargets.cmake
+    )
+
+    # Installing headers
+    install(
+        DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/casbin
+        DESTINATION include
+    )
+
+    set(CMAKE_EXPORT_PACKAGE_REGISTRY ON)
+    export(PACKAGE casbin)
+
+    message(CHECK_PASS " The targets can now be imported with find_package(casbin)")
+    message(STATUS "[casbin]: Build the \"install\" target and add \"${CMAKE_INSTALL_PREFIX}/include\" to you PATH for casbin to work")
+endif()

README.md

@@ -33,6 +33,8 @@ production-ready | production-ready | production-ready | production-ready
 [PyCasbin](https://github.com/casbin/pycasbin) | [Casbin.NET](https://github.com/casbin-net/Casbin.NET) | [Casbin-CPP](https://github.com/casbin/casbin-cpp) | [Casbin-RS](https://github.com/casbin/casbin-rs)
 production-ready | production-ready | beta-test | production-ready
 
+**Note**: PyCasbin-on-CPP is available to use. Refer to the [documentation](./bindings/README.md) for installation and usage.
+
 ## Supported models
 
 1. [**ACL (Access Control List)**](https://en.wikipedia.org/wiki/Access_control_list)
@@ -113,8 +115,10 @@ https://casbin.org/docs/en/tutorials
 
 ## Integrating Casbin to your project through CMake
 
-Here is a [working project](https://github.com/EmperorYP7/casbin-CMake-setup) to demonstarte how to set up your CMake
-configurations to integrate casbin.
+### Without installing casbin locally
+
+Here is a [working project](https://github.com/EmperorYP7/casbin-CMake-setup) to demonstarte how to set up 
+your CMake configurations to integrate casbin without any prior installations.
 
 You may integrate casbin into your CMake project through `find_package`. **It is assumed that you're using CMake >= v3.19.**
 
@@ -161,6 +165,57 @@ target_include_directories(myexec PRIVATE ${myexec_INCLUDE_DIR})
 
 Do remember to include `casbin_SOURCE_DIR/include` directory wherever casbin's functions are utilised.
 
+### With local installation
+
+You may integrate casbin into your CMake project through `find_package`. 
+**It is assumed that you're using CMake >= v3.19**
+
+1. Clone/checkout to [`casbin/casbin-cpp:master`](https://github.com/EmperorYP7/casbin-cpp/tree/ctest-setup)
+    ```bash
+    git clone https://github.com/casbin/casbin-cpp.git
+    ```
+
+2. Open terminal/cmd in the root directory of the project:
+
+    ```bash
+    mkdir build
+    cd build
+    cmake ..
+    ```
+
+    **Note:** Look up for the logs of this step. And add the path indicated by the log into your PATH/project include directory.
+    The log message you're looking for should be something like this:
+    ```bash
+    [casbin]: Installing casbin ...
+    [casbin]: Installing casbin ... -  The targets can now be imported with find_package(casbin)
+    [casbin]: Build the "install" target and add "/usr/local/include" to you PATH for casbin to work
+    ```
+
+3. After the project is configured successfully, build it:
+    ```bash
+    cmake --build . --config Release
+    ```
+
+4. Install casbin:
+
+    ```bash
+    cmake --build . --config Release --target install
+    ```
+    Now, casbin has been installed and ready to go.
+
+5. In your project's CMake file, add
+    ```cmake
+    find_package(casbin REQUIRED)
+    ```
+    This will import all the targets exported by casbin to your project
+
+6. Link against casbin (Refer to Step 2's **Note** to get the value of `MY_INCLUDE_DIR` for your system):
+    ```cmake
+    set(MY_INCLUDE_DIR "/usr/local/include")
+    target_include_directories(MyTargetName PRIVATE ${MY_INCLUDE_DIR})
+    target_link_libraries(MyTargetName PRIVATE casbin::casbin)
+    ```
+
 ## Installation and Set-Up
 
 ### Build instructions for all platforms
@@ -194,8 +249,8 @@ Do remember to include `casbin_SOURCE_DIR/include` directory wherever casbin's f
     cmake --build . --target install
     ```
 
-    - For **Windows**, this will install `casbin.lib` to `C:/Program Files/casbin-cpp/lib`
-    and the headers to `C:/Program Files/casbin-cpp/include`.
+    - For **Windows**, this will install `casbin.lib` to `C:/Program Files/casbin/lib`
+    and the headers to `C:/Program Files/casbin/include`.
     - For Unix based OS i.e. **Linux and macOS**, this will install `casbin.a` to `usr/local/lib` 
     and the headers to `usr/local/include`.
 

bindings/README.md

@@ -0,0 +1,129 @@
+## Language Bindings for Casbin
+
+Casbin-CPP provides language bindings to compound the advantages of different languages and to make 
+authorization easier and faster.
+
+At present, casbin-cpp provides language bindings for Python.
+
+## Python Bindings
+
+### Installing the PyCasbin module
+
+It is assumed you have CMake >=v3.19 and Python >= 3.2 installed.
+
+1. Clone/download the project:
+    ```bash
+    git clone https://github.com/casbin/casbin-cpp.git
+    ```
+
+2. Make a build directory and generate project files through CMake:
+    ```bash
+    mkdir build
+    cd build
+    cmake ..
+    ```
+    **Note:** Kindly look at the log message to find the directory you need to add in your `sys.path` (Step 5). The log may look like this:
+    ```bash
+    [pycasbin]: Build "pycasbin" target for Python Bindings
+    [pycasbin]: Add "lib/python3.9/site-packages" to your sys.path/USER_SITE variable if not already present
+    ```
+
+3. Build the python bindings (`pycasbin` target):
+    ```bash
+    cmake --build . --config Release --target pycasbin
+    ```
+
+4. Install the `pycasbin` module:
+    ```bash
+    cmake --build . --config Release --target install
+    ```
+    This will install the module to: 
+    - `<prefix>/lib/site-packages` on Windows.
+    - `<prefix>/lib/python3.x/site-packages` on UNIX.
+
+    **Note:** The actual install path can be deduced in the log output of Step 2.
+
+5. Add the correct `site-packages` directory path to `sys.path` or `USER_SITE` of your current python configuration if not already present.
+
+Now, you're ready to go!
+
+### Usage
+
+It is assumed that you have `pycasbin` module correctly installed on your system.
+
+First, we import the pycasbin module to a python source file:
+
+```python
+import pycasbin as casbin
+```
+
+Suppose we want a function to check authorization of a request:
+
+```python
+def isAuthorized(req):
+    result = True
+    if result:
+        print('Authorized')
+    else
+        print('Not authorized!')
+```
+
+Here, the request can be a list or a dictionary in the forms:
+
+```python
+req = ['subject1', 'object1', 'action1'] # and so on..
+
+req = {
+    "sub": "subject1",
+    "obj": "object1",
+    "act": "action1"  # ... and so on
+}
+```
+
+We can Enforce this request (or compute the `result` of this request) through `casbin.Enforce()`. 
+For that, we need to create a `casbin.Enforcer`:
+
+```python
+e = casbin.Enforcer('path/to/model.conf', 'path/to/policy.csv')
+```
+Make sure that the paths are relative to the current python source file or an absolute path.
+
+Apart from the regular `Enforcer`, you may also use `CachedEnforcer`
+depending on your use case.
+
+Incorporating the `Enforcer` in our example gives us:
+
+```python
+def isAuthorized(req):
+    result = e.Enforce(req)
+    if result:
+        print('Authorized')
+    else
+        print('Not authorized!')
+```
+
+Rest of the method's name is on par with casbin-CPP.
+
+#### Summary
+
+This sums up the basic usage of pycasbin module:
+
+```python
+import pycasbin as casbin
+
+e = casbin.Enforcer('path/to/model.conf', 'path/to/policy.csv')
+
+def isAuthorized(req):
+    result = e.Enforce(req)
+    if result:
+        print('Authorized')
+    else
+        print('Not authorized!')
+
+isAuthorized(['subject1', 'object1', 'action1'])
+isAuthorized(['subject2', 'object2', 'action2'])
+# ... and so on
+```
+
+If you've done everything right, you'll see your output
+without any errors.

bindings/python/CMakeLists.txt

@@ -30,7 +30,7 @@ set(HEADERS
 
 Python_add_library(pycasbin MODULE ${SOURCES} ${HEADERS})
 
-target_include_directories(pycasbin PUBLIC ${CMAKE_SOURCE_DIR}/include)
+target_include_directories(pycasbin PUBLIC ${CASBIN_INCLUDE_DIR})
 
 set_target_properties(pycasbin PROPERTIES
     PREFIX ""
@@ -78,16 +78,19 @@ else()
     set(Python_VARIANT_PATH lib${LIB_SUFFIX}/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages)
 endif()
 
-message("${Python_VARIANT_PATH}")
-
 # For testing
 install(
     TARGETS pycasbin
     LIBRARY DESTINATION ${CMAKE_SOURCE_DIR}/tests/python
 )
 
-# For actual installation
-install(
-    TARGETS pycasbin
-    LIBRARY DESTINATION ${Python_VARIANT_PATH}
-)
+if(CASBIN_INSTALL)
+    # For actual installation
+    install(
+        TARGETS pycasbin
+        LIBRARY DESTINATION ${Python_VARIANT_PATH}
+    )
+
+    message(STATUS "[pycasbin]: Build \"pycasbin\" target for Python Bindings")
+    message(STATUS "[pycasbin]: Add \"${Python_VARIANT_PATH}\" to your sys.path/USER_SITE variable if not already present")
+endif()

casbin/CMakeLists.txt

@@ -12,7 +12,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-set(CASBIN_SOURCE
+set(CASBIN_SOURCE_FILES
     abac_data.cpp
     enforcer.cpp
     enforcer_cached.cpp
@@ -71,10 +71,10 @@ set(CASBIN_SOURCE
 # Setting to C++ standard to C++17
 set(CMAKE_CXX_STANDARD 17)
 
-add_library(casbin STATIC ${CASBIN_SOURCE})
+add_library(casbin STATIC ${CASBIN_SOURCE_FILES})
 
-target_precompile_headers(casbin PUBLIC pch.h)
-target_include_directories(casbin PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+target_precompile_headers(casbin PRIVATE pch.h)
+target_include_directories(casbin PRIVATE ${CASBIN_SOURCE_DIR})
 
 set_target_properties(casbin PROPERTIES 
     PREFIX ""

casbin/abac_data.h

@@ -14,8 +14,8 @@
 * limitations under the License.
 */
 
-#ifndef ABAC_H
-#define ABAC_H
+#ifndef CASBIN_ABAC_H
+#define CASBIN_ABAC_H
 
 #include "attribute_types.h"
 
@@ -109,4 +109,4 @@ typedef ABACData ABACData;
 const std::shared_ptr<ABACData> GetDataObject(const AttributeMap& attribs);
 }
 
-#endif
+#endif // CASBIN_ABAC_H

casbin/casbin.h

@@ -19,9 +19,9 @@
 #ifndef CASBIN_CPP_CASBIN_H
 #define CASBIN_CPP_CASBIN_H
 
+#include "casbin_types.h"
 #include "casbin_enforcer.h"
 #include "casbin_helpers.h"
-#include "casbin_types.h"
 #include "duktape/duktape.h"
 #include "duktape/duk_config.h"